Documents

Create and manage forms that drivers fill out in the Samsara Driver App using the Documents API.

Overview

Samsara Documents are custom forms that drivers can fill out in the Samsara Driver App. Fleet Administrators can manage documents and create custom document templates (called Document Types) in the Samsara Dashboard. See the Documents knowledge base article to understand how Documents work in the Samsara Dashboard and Driver App.

Here are the main tasks associated with Samsara’s Documents API:

• Pull available Document Types that serve as a template for individual documents
• Create a document for a driver to fill out
• Configure a document submission webhook
• Pull submitted documents created or updated during a given time period
• Generate document PDF files

See below for details on Document Types and the Document Object.

Document Types

Document Types are templates that describe the structure of documents for drivers to fill out in the Driver App. For example, an organization might have an Accident document type, a Bill of Lading document type, a Citation document type, and many more.

Document Types are managed in the Samsara Dashboard. Fleet managers can use out-of-the-box document types provided by Samsara, or they can define their own custom document types by defining the fields that make up that type of document.

Retrieve document types via API

The Fetch document types API pulls all available documents types for your organization.

curl --request GET 'https://api.samsara.com/v1/fleet/drivers/document_types' \
--header 'Authorization: Bearer YOUR_API_TOKEN'

Document Type Object

Field	Description
orgId	The ID of the organization that created the document type.
uuid	The universal identifier of the document type.
name	Name of the document type.
fieldTypes	The fields that make up the document. Includes conditional fields.
conditionalFieldSections	A description of which fields trigger conditional fields.

Field Types

The fieldTypes array lists the fields that make up the document type. Each field has a label, a valueType, and optional metadata. Available value types: ValueType_Number, ValueType_String, ValueType_Photo, ValueType_MultipleChoice, ValueType_DateTime, ValueType_Signature.

Optional metadata depending on the value type:

• numberValueTypeMetadata — describes the number of decimals a numeric field can have
• multipleChoiceValueTypeMetadata — describes the options of a multiple choice field
• signatureValueTypeMetadata — provides legal text associated with the signature

Conditional Fields

When defining the document type, an admin can create conditional fields that appear only when the driver selects a certain multiple-choice option. The definitions of conditional fields appear in the fieldTypes array along with the standard fields. The conditionalFieldSections array lists the set of conditions that can trigger them.

"conditionalFieldSections": [
  {
    "triggeringFieldIndex": 1,
    "triggeringFieldValue": "Yes",
    "conditionalFieldFirstIndex": 2,
    "conditionalFieldLastIndex": 2
  },
  {
    "triggeringFieldIndex": 1,
    "triggeringFieldValue": "No",
    "conditionalFieldFirstIndex": 3,
    "conditionalFieldLastIndex": 3
  }
]

Each entry describes a condition and a section of fields triggered by it. triggeringFieldIndex indicates which field triggers the condition (0-indexed). triggeringFieldValue indicates which multiple-choice value must be selected. conditionalFieldFirstIndex and conditionalFieldLastIndex describe the range in fieldTypes activated by the condition.

Documents

Documents are specific instances of a given document type. They are either created in the Driver App or via API. See Creating Documents for a guide on how to create documents via API.

Retrieve documents via API

Documents can be retrieved by one of the following API endpoints:

• Fetch all documents — Returns an array of document objects created or updated during a provided time range
• Fetches a document — Returns a document object by its ID

Document Object

Field	Description
orgId	The ID of the organization this document belongs to.
driverId	The ID of the driver that submitted the document.
id	The document’s ID.
driverCreatedAtMs	Unix UTC timestamp (ms) of when the document was created in the Driver App.
serverCreatedAtMs	Unix UTC timestamp (ms) of when the document was uploaded to the Samsara server.
serverUpdatedAtMs	Unix UTC timestamp (ms) of when the document was last updated.
dispatchJobId	The ID of a route stop this document is associated with.
state	Required, Submitted, or Archived.
documentType	The name of the Document Type for this document.
vehicleId	The ID of the vehicle the driver had selected when the document was submitted.
fields	The fields and values for the document.
name	The name the driver provided for this document.

See the Fetches a document API docs for full details.

Fields

The fields array of the document contains all the fields and their values. The structure of these fields is defined by the document’s Document Type.

All fields have:

• label — same as the label defined by the given document type
• valueType — the type of the field. Valid values: ValueType_String, ValueType_MultipleChoice, ValueType_Number, ValueType_DateTime, ValueType_Photos, ValueType_Signature
• The actual value for the field, named according to the value type (e.g. stringValue, multipleChoiceValue, etc.)
• value — deprecated, matches the property specific to the field’s value type

String Fields

{
  "label": "Load #",
  "valueType": "ValueType_String",
  "stringValue": "123ABC",
  "value": "123ABC"
}

Multiple Choice Fields

The multipleChoiceValue property is an array representing which option of the multiple-choice field is selected.

{
  "label": "Did you drop the trailer?",
  "valueType": "ValueType_MultipleChoice",
  "multipleChoiceValue": [
    { "value": "Yes", "selected": true },
    { "value": "No", "selected": false }
  ]
}

Number Fields

{
  "label": "# of pieces",
  "valueType": "ValueType_Number",
  "numberValue": 12,
  "value": 12
}

The number of decimal places supported is described by numberValueTypeMetadata in the document’s Document Type.

Datetime Fields

{
  "label": "Time unloaded",
  "valueType": "ValueType_DateTime",
  "dateTimeValue": { "dateTimeMs": 1593643324000 },
  "value": { "dateTimeMs": 1593643324000 }
}

dateTimeMs is measured in milliseconds since the Unix epoch in UTC.

Photo Fields

The photoValue will be an array of photos, each containing a url to the photo uploaded by the driver. The URL is valid for 1 hour from the time it is generated; you may retrieve the document again to get new URLs.

{
  "label": "Unload Picture",
  "valueType": "ValueType_Photo",
  "photoValue": [
    { "url": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/..." }
  ]
}

Signature Fields

The signatureValue contains the name of the signature, the time of signature in milliseconds since the Unix epoch in UTC, and a URL to the PNG version of the signature. This URL expires after 24 hours.

{
  "label": "Consignee",
  "valueType": "ValueType_Signature",
  "signatureValue": {
    "name": "Driver Name",
    "signedAtMs": 1593713506446,
    "url": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/..."
  }
}