Creating Documents

Create documents for drivers to fill out, or submit documents on a driver’s behalf, using the Documents API.

Overview

The Create a document endpoint allows you to perform two main actions:

• Create a document for a driver to fill out in the Driver App
• Submit a document on a driver’s behalf

Document State

A document’s state determines if it is created for a driver to fill out in the Driver App or if the document is submitted on behalf of the driver.

• Setting a document’s state to Required creates a document for the driver to fill out in the Driver App. The most common use case for this is Creating Stop Tasks in Routes. The document will be marked as “Required” in the Driver App.
• Setting a document’s state to Submitted will submit the document on behalf of the driver. A fleet admin will then be able to view the document in the Samsara Dashboard. It will appear as if the driver submitted the document from the Driver App.

The state field defaults to Required.

Create Document Request

The Create a document endpoint allows you to create or submit a document for a given driver. For example:

curl --request POST 'https://api.samsara.com/fleet/documents' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "documentTypeUuid": "abc-123",
    "driverId": "123456",
    "fields": []
}'

The table below describes the properties available for the document creation request.

Field	Description
documentTypeUuid	The UUID of the Document Type that describes the template for this document.
name	An optional name for this document.
fields	The fields for this document. This will either define default values or provide values that are submitted on behalf of the driver.
state	Valid values: Required or Submitted. Defaults to Required.
dispatchJobId	The ID of a route stop if you want to associate this document with a particular route stop.
notes	Optional notes for the document.

Defining Fields

The fields array of the document creation request should list fields and values in the same order they appear in the Document Type for the given document.

For example, list the Load # field first, then the Did you drop the trailer? field, and so on. The field order must match the order returned by the Document Types API.

{
  "documentTypeUuid": "abc-123",
  "state": "required",
  "fields": [
    { "type": "string", "label": "Load #" },
    { "type": "multipleChoice", "label": "Did you drop the trailer?" }
  ]
}

When field values are left blank, they assume a default value. If a document is in the Required state, the driver can fill out the values through the driver app. If a document is in the Submitted state, the document will contain default values for any fields left blank.

Field Values

All fields have:

• label — same as the label defined by the document type
• type — one of photo, string, number, multipleChoice, signature, dateTime, scannedDocument, barcode
• The actual value for the field. This property can be omitted if you wish for the field to assume a default value.

String Fields

{
  "type": "string",
  "value": { "stringValue": "Test123" },
  "label": "Load #"
}

Default if stringValue is omitted: ""

Multiple Choice Fields

{
  "type": "multipleChoice",
  "value": {
    "multipleChoiceValue": [
      { "selected": true, "value": "Yes" }
    ]
  },
  "label": "Did you drop the trailer?"
}

Only one option may be selected. If an option is not selected, it may be omitted.

Default if multipleChoiceValue is omitted: [] (none of the options were selected).

Number Fields

{
  "type": "number",
  "value": { "numberValue": 12 },
  "label": "# of pieces"
}

Default if numberValue is omitted: 0.

Datetime Fields

{
  "type": "dateTime",
  "value": {
    "dateTimeValue": { "dateTime": "2023-09-08T02:53:53Z" }
  },
  "label": "Time unloaded"
}

dateTime is measured in RFC 3339 format.

dateTimeValue cannot be omitted. If you wish to set this field to a default value, submit "dateTimeValue": {}.

Default if dateTimeMs is omitted: 0 (appears as if the field was left blank).

Photo Fields

Photos cannot be submitted via the API. The value for a photo field must be left blank.

{
  "type": "photo",
  "label": "Unload Picture"
}

When a document is in the Required state, the driver will be able to submit photos through the Driver App.

Signature Fields

Signatures cannot be submitted via the API. The value for a signature field must be left blank.

{
  "type": "signature",
  "label": "Consignee"
}

When a document is in the Required state, the driver will be able to capture a signature through the Driver App.