Forms and workflows

Forms let you digitize a wide range of tasks—like inspections, proofs of delivery, audits, or checklists—and assign them to either a specific driver or a specific route stop. You can configure Samsara so that when a form is assigned to a route stop, a driver cannot proceed to the next stop until the form is submitted.

This guide explains how to:

Retrieve a form template to understand which fields you can pre-fill.
Create and assign a form submission:
- Either to a route stop (most common for TMS flows).
- Or directly to a driver (or any other Samsara user).
Pre-populate forms with relevant data.
Receive notifications or poll for completed forms.

Important: The old API for creating “documents” is no longer applicable. Please use the new Forms APIs outlined below.

Overview

Retrieve Template: To pre-populate fields, you must know the template id, its revisionId, and the field IDs.
Create Form Submission: Use POST /form-submissions and specify either:
- routeStopId: The form is tied to a particular stop. The driver will be required to complete the form before leaving the stop.
- assignedTo: The form is assigned to a specific driver or user.
(Optional) Pre-fill: Provide field values in your request if you want the form partially or fully completed when the driver sees it.
Submit & Complete: Drivers see assigned forms in the Samsara Driver App. They can submit answers there, triggering a near real-time update in your TMS if you handle webhooks.
(Optional) Status Updates: Modify assigned forms (e.g., reassign or archive) with PATCH /form-submissions/{formSubmissionId}.

1. Retrieve a Form Template

Each form submission references:

A Template ID (e.g., 9e118726-41e2-5ba9-8c1a-eb78e8a391ac)
A Template Revision ID (e.g., 889fd3ae-b378-452a-b7b7-4b9a86cac4d9)

When a template changes—adding or removing fields, etc.—Samsara creates a new immutable revision.

Example request (coming soon!)

curl --location 'https://api.samsara.com/form-templates' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>'

Example response

{
  "data": [
    {
      "id": "456461",
      "revisionId": "567572",
      "title": "Forklift Inspection",
      ...
      "fields": [
        {
          "id": "12345",
          "label": "Engine Hours",
          "type": "number",
          ...
        },
        ...
      ]
    }
  ],
  "pagination": {
    "endCursor": "...",
    "hasNextPage": true
  }
}

Tip: Inspect the fields array carefully if you plan to pre-populate the form. Each field has an internal id required when setting the initial value.

2. Create and Assign a Form Submission

Use POST /form-submissions to create a new form submission. You must specify:

formTemplate: With id and revisionId.
status: Typically "notStarted".
One of:
- routeStopId (most common for TMS workflows).
- assignedTo (driver or user).

2.1 Assigning a Form to a Route Stop

If your TMS solution creates and manages routes, attach the form to a specific stop. Drivers see forms on their route. If the form is “required,” the driver must complete it before the app allows them to progress.

Example request

curl --location 'https://api.samsara.com/form-submissions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "routeStopId": "6118765423",
  "status": "notStarted",
  "formTemplate": {
    "id": "9e118726-41e2-5ba9-8c1a-eb78e8a391ac",
    "revisionId": "889fd3ae-b378-452a-b7b7-4b9a86cac4d9"
  }
}'

Example response

{
  "data": {
    "id": "a37a256e-1c77-43bc-9e83-73484b3c7bf5",
    "formTemplate": {
      "id": "9e118726-41e2-5ba9-8c1a-eb78e8a391ac",
      "revisionId": "4a6d8108-9238-48c1-b8df-b16bfe0bcb39"
    },
    "routeStopId": "6118765423",
    "status": "notStarted",
    "isRequired": true,
    ...
  }
}

2.2 Assigning a Form Directly to a Driver

If you prefer to directly assign a form to a driver (or user) instead of tying it to a route stop, pass their Samsara ID and set type to "driver" or "user".

curl --location 'https://api.samsara.com/form-submissions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "assignedTo": {
    "id": "52514325",
    "type": "driver"
  },
  "status": "notStarted",
  "formTemplate": {
    "id": "9e118726-41e2-5ba9-8c1a-eb78e8a391ac",
    "revisionId": "889fd3ae-b378-452a-b7b7-4b9a86cac4d9"
  }
}'

3. Pre-populating a Form

A key benefit of forms is the ability to save your drivers from manual re-entry of common data—like trailer IDs, customer addresses, or purchase order details.

To pre-populate a form, include a fields array in your request, specifying the IDs of each field and the value(s) you want. For instance, if your template has a text field with ID 4f8280be-4ad6-480e-8dc8-b73a15275dfd, you can set:

"fields": [
  {
    "id": "4f8280be-4ad6-480e-8dc8-b73a15275dfd",
    "type": "text",
    "textValue": {
      "value": "ACME Co."
    }
  }
]

Full request example (pre-filling multiple fields, assigned to a driver):

curl --location 'https://api.samsara.com/form-submissions' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "formTemplate": {
    "id": "3ff41093-6da1-5d57-9cec-fa2536a03d09",
    "revisionId": "39eeaba2-556b-4c32-9fd8-5776ba508929"
  },
  "status": "notStarted",
  "assignedTo": {
    "id": "52514325",
    "type": "driver"
  },
  "dueAtTime": "2025-02-04T00:00:00.000Z",
  "fields": [
    {
      "id": "685d5c46-8118-40f4-b9d7-8fabc98ab464",
      "type": "asset",
      "assetValue": {
        "asset": {
          "id": "281474994182986"
        }
      }
    }
  ]
}'

4. Driver/Worker Experience

Once a form submission is created, the assigned driver (or the driver at the assigned route stop) sees a new task in the Samsara Driver App inbox. The form can be accessed immediately, and any pre-filled data is shown to the driver, who can update or finalize it as needed.

5. Updating or Reassigning Forms

After creation:

You cannot add or modify pre-filled answers. To change the responses, the driver or user must edit directly in the Samsara Driver App.
You can update the form’s metadata, such as its status, or even change its assignment to a different user or route stop by using PATCH /form-submissions/{formSubmissionId}.

For example, to update the status to "changesRequested" or to change the assignee:

curl --location --request PATCH 'https://api.samsara.com/form-submissions/47de8234-0196-430b-800d-b49a7b604dc5' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "status": "changesRequested",
  "assignedTo": {
    "id": "98989898",
    "type": "driver"
  }
}'

6. Handling Completed Forms

You can track form completion in two ways:

Poll: Use GET /form-submissions/stream with a time range filter to see which forms have changed.
Webhook: Subscribe to FormSubmitted events to receive real-time updates when a form is submitted via the Driver App.

Note: Forms submitted directly from the dashboard currently do not trigger a webhook event, but this is on the roadmap.

Summary & Key Points

Use the new Forms API: The old “document creation” API is deprecated.
Driver or Route Stop Assignment: Assign forms to either:
- A route stop (routeStopId)
- An individual (assignedTo with type: driver or user)
Pre-Fill Data: Reduce driver data entry by specifying field IDs and values.
Immutable Answers: Once created, pre-filled answers cannot be updated programmatically. Drivers can edit answers in the mobile app, or you can create a new form if you need changes.
Stay Synchronized: Poll or subscribe to webhooks to keep your TMS updated as forms move from "notStarted" to "inProgress" to "completed" or "approved".

By following this pattern, your TMS can create, assign, and track required forms—such as proofs of delivery or inspection checklists—ensuring drivers have a streamlined workflow and your system remains up to date with real-time form data.