Samsara Developer Portal

Integrate your data with the Samsara API, customize the Samsara experience, and join a community of developers building with Samsara.

Get Started

Creating Stop Tasks

Define tasks for a driver to complete using Samsara's Documents feature

📘

For a general introduction to the Samsara REST API, see the Getting Started guide.

For an overview on Routing concepts, see the Routing overview page.

What are we building?

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 Route Stop and Driver IDs

In order to create a task for a given route stop and driver, you associate the IDs of those respective objects with the document you're creating.

{
  "id": 4302682573,
  "name": "Basic Route",
  "driver_id": 1654973,
  "dispatch_jobs": [
    {
      "id": 4328620283,
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000
      ...
    }
  ]
  ...
}

The route contains an id, a driver_id, and an array of dispatch_jobs. Each dispatch job also contains an id.

You must save the driver_id and dispatch job id that you want to create the stop task for.

  • driver_id: 1654973
  • id of the dispatch job: 4328620283

Retrieving 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/v1/fleet/drivers/document_types' \
--header 'Authorization: Bearer <token>'
{
  "documentTypes": [
    {
      "orgId": 53729,
      "uuid": "c3d04f1c-18f8-45fe-8c23-8f40f83851e0",
      "name": "Stop Tasks",
      "fieldTypes": [
        {
          "label": "Load #",
          "valueType": "ValueType_String"
        },
        {
          "label": "Did you drop the trailer?",
          "valueType": "ValueType_MultipleChoice",
          "multipleChoiceValueTypeMetadata": {
            "multipleChoiceOptionLabels": [
              {
                "label": "Yes"
              },
              {
                "label": "No"
              }
            ]
          }
        },
        {
          "label": "# of pieces",
          "valueType": "ValueType_Number",
          "numberValueTypeMetadata": {
            "numDecimalPlaces": 0
          }
        },
        {
          "label": "Time unloaded",
          "valueType": "ValueType_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.

Creating 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 dispatch job (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.

The API endpoint for creating a route stop tasks takes the following form:

POST /v1/fleet/drivers/{driver_id}/documents

Let's take a look at how to create the route stop task described in this example:

POST /v1/fleet/drivers/1654973/documents
{
  "dispatchJobId": 4337079369,
  "documentTypeUuid": "c3d04f1c-18f8-45fe-8c23-8f40f83851e0",
  "fields": [
    {
      "label": "Load #",
      "valueType": "ValueType_String"
    },
    {
      "label": "Did you drop the trailer?",
      "valueType": "ValueType_MultipleChoice"
    },
    {
      "label": "# of pieces",
      "valueType": "ValueType_Number"
    },
    {
      "label": "Time unloaded",
      "valueType": "ValueType_DateTime",
      "dateTimeValue": {}
    }
  ]
}

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

Updated 18 days ago



Creating Stop Tasks


Define tasks for a driver to complete using Samsara's Documents feature

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.