Overview

This guide describes how to define route stop tasks using Samsara Documents. Please see the Documents knowledge base article for an overview of documents and document types.

Here are the steps for defining a route stop task:

1. Save the route stop ID and driver ID for the given stop and driver you want to associate the task with.
2. Retrieve the relevant document type for the route stop task.
3. Create a document for the given driver and associate it with the route stop. This will list the document in the Tasks section of the Driver App for a given route stop.

📘

Generic Documents versus Route Stop Tasks

Drivers can submit generic documents at any time from the Documents tile in the Samsara Driver App.

This guide shows how to create a required document that becomes a task when associated with a given stop.

Save the Stop and Driver IDs

In order to create a stop task, you should retrieve the driverId and the [stops].id of the driver and stop you want to create the task for:

curl --request GET 'https://api.samsara.com/fleet/routes/4319644915' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>'

{
    "data": {
        "id": "4319644915",
        "name": "Route 1234",
        "driverId": "1654973",
        "stops": [
            {
                "id": "4439748157",
                "externalIds": {
                    "routePlanningSystem": "stop1234"
                },
                "scheduledDepartureTime": "2021-05-07T14:30:00.000Z",
                ...
            },
            ...
        ],
        ...
    }
}

Note that the Documents API does not currently support external IDs, so you must use the Samsara-provided driverId and [stops].id fields, and not the external IDs.

Values from the example above:

• driverId: 1654973
• stops[0].id: 4439748157

Retrieve the Document Types

Documents are created using document types. Document types define the fields for a document.

Here's an example of a document type with four fields:

Let's take a look at a sample request that retrieves the list of document types available:

curl --request GET 'https://api.samsara.com/fleet/document-types' \
--header 'Authorization: Bearer <token>'

{
  "data": [
    {
      "name": "Stop Tasks",
      "orgId": 29566,
      "id": "29212f4d-b176-4766-99e8-dc3e3f8c3a1b",
      "fieldTypes": [
        {
          "label": "Load #",
          "requiredField": false,
          "fieldType": "string"
        },
        {
          "label": "Did you drop the trailer?",
          "requiredField": false,
          "fieldType": "multipleChoice",
          "multipleChoiceFieldTypeMetaData": [
            {
              "label": "Yes"
            },
            {
              "label": "No"
            }
          ]
        },
        {
          "label": "# of pieces",
          "requiredField": false,
          "fieldType": "number",
          "numberFieldTypeMetaData": {
            "numberOfDecimalPlaces": 0
          }
        },
        {
          "label": "Time unloaded",
          "requiredField": false,
          "fieldType": "dateTime"
        }
      ]
    }
  ]
}

The response above includes an array of documentTypes. Each document type has a uuid and an array of fieldTypes. The document type we want to use is called Stop Tasks. This document type has four fields:

• Load # which is a string field.
• Did you drop the trailer? which is a multiple-choice field. The options for this field are:
  • Yes
  • No
• # of pieces which is a number field. This number field is constrained to 0 decimal places.
• Time unloaded which is a DateTime field.

We will use this information when creating the document to be the stop task.

Create the Document

When creating the document for the route stop task, you will:

• Use the driver ID retrieved in step 1 as a path parameter in the API endpoint.
• Construct a JSON request body that:
  • Includes the ID of the route stop from step 1.
  • Includes the UUID of the document type from step 2. In this case, it is the UUID for the "Stop Tasks" document type.
  • Enumerate the fields of the document in the request body.

curl --request POST 'https://api.samsara.com/fleet/documents' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
  "state": "required",
  "documentTypeId": "29212f4d-b176-4766-99e8-dc3e3f8c3a1b",
  "routeStopId": "4439748157",
  "fields": [
    {
      "type": "string",
      "label": "Load #"
    },
    {
      "type": "multipleChoice",
      "label": "Did you drop the trailer?"
    },
    {
      "type": "number",
      "label": "# of pieces"
    },
    {
      "type": "dateTime",
      "label": "Time unloaded"
    }
  ],
  "driverId": "1654973"
}'

The request above will create the following form for the driver to fill out at the given route stop: