Create and Assign Forms

Digitize forms, build workflows, and automate processes by creating and assigning Samsara form submissions.

Easily create digital forms like inspections, checklists, audits, and reports for any vehicle, asset, or site inspection. Then, assign those forms to workers to submit. You’ll manage form templates from your Samsara dashboard, then you can use the API to create, assign, and pre-populate forms for workers.

Key concepts

Worker, Driver, and User

A Worker is a broad category that includes anyone assigned to complete a form submission. Workers can be either Drivers or Users in Samsara.

• Drivers: Users who have access to driver-specific features, such as vehicle selection, Hours of Service (HoS), and DVIRs. Forms assigned to drivers will appear in the Samsara Driver App alongside their other workflows.
• Users: Dashboard users who do not have access to driver-related features but can still be assigned forms. These users typically include safety supervisors, equipment operators, and field workers.

Admins can configure a worker as a non-driver by enabling the “Hide Driving Features” setting, or by using the Update a driver API with the hasDrivingFeaturesHidden boolean. This setting removes driver-specific functionality while still allowing access to Forms and Training within the Driver App. When creating a form submission, you can assign it to either a driver or a user by specifying the corresponding type in the assignedTo object.

1. Retrieve a form template

   Before you can create a form, you need to know the template ID and template revision ID. Use the Get a list of form templates endpoint to retrieve the list of form templates.

   The form-templates API is coming soon. In lieu of using the form-templates API to retrieve the template ID and template revision ID, you can submit a form and retrieve the form submission from the API to find the template ID and revision ID. The form submission UUID is available in the URL when viewing a form submission in the dashboard.

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

   The response includes each template’s id, revisionId, title, description, fields, and sections. Identify the template you want workers to fill out by id.

   The structure of the template (i.e. the exact array of questions, fields, and nested items) is needed if you plan to pre-fill responses. Each field has an internal reference or ID you must use when populating data. For more detail on how to interpret these fields, refer to the Form Field Types guide.

2. Create and assign a form submission

   Either a routeStopId or an assignedTo worker is required when creating a form submission. Form submissions require a status and formTemplate id and revisionId.

   As form templates evolve and fields are added or removed, or options are added or removed, new immutable revisions are created to keep any related form submissions and revisions of templates in lock step.

   Use the Create a form submission endpoint to create a form submission and optionally assign it to a worker (or route).

   Creating and assigning a blank form to a worker

   This example creates a new form submission for a template and assigns it to a driver. You can also assign forms to dashboard users by setting the type to user in the assignedTo object. No fields are passed in this request, so the driver will need to populate all of the answers when they submit the form.

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

   Creating and assigning a blank form to a route stop

   Instead of assigning to a driver, the form is assigned to a route stop. By assigning the form to a route stop, the driver must submit the form before moving on from this stop.

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

   Pre-populating a basic form

   The form template contains an asset field. The trailer’s ID can be used to pre-populate the “Trailer” field in this “Trailer Inspection” by including the field in the list of fields. See the full list of Form fields for reference to understand what data is required for each field answer.

   curl --location 'https://api.samsara.com/form-submissions' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer YOUR_API_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"
         }
       }
     }]
   }'
   
3. Confirm assignment in the Driver App

   When you create a new form submission, the assigned driver (or the driver assigned to a particular route) will receive:

   • A push notification on the Samsara Driver App, indicating that a new form is ready.
   • A task in the Driver Inbox. The assigned form will appear with any data you have pre-filled.

   Drivers can open the task, review the pre-filled answers, edit if needed, and submit. You can also view a list of assigned form submissions in the dashboard for confirmation.

4. Edit an assigned form

   Once a form submission is created, it’s not possible to change any of the prefilled form answers via the API.

   Use the Update a form submission endpoint if you need to modify who a form is assigned to, change the status, or archive a form. Changing the status of a form is especially useful for approval-based workflows.

   curl --location --request PATCH 'https://api.samsara.com/form-submissions' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer YOUR_API_TOKEN' \
   --data '{
     "id": "47de8234-0196-430b-800d-b49a7b604dc5",
     "title": "Updated title"
   }'
   

   You cannot pre-fill additional fields after the form submission is created. Pre-filling must occur during the initial POST /form-submissions call.

Listen for form updates

To keep your system in sync with the latest forms submitted, you can either poll the Samsara API for form submission changes or handle webhook events that notify you when forms are submitted.

Polling the /form-submissions/stream endpoint

Periodically call the Get a stream of form submissions endpoint and compare the response to your local records. This API requires startTime and endTime as filters.

Handling FormSubmitted webhook events

Samsara can send a webhook notification when forms are submitted. Subscribe to FormSubmitted events to receive near real-time notifications and update your database or start workflows.

Forms submitted via the dashboard (as opposed to drivers via mobile) do not yet trigger webhooks, however this is on our roadmap.

Summary

• Identify the form template you want filled out by calling GET /form-templates.
• Create a form submission with POST /form-submissions, including pre-filled data if you choose.
• Assign the form to a driver or route by setting assigneeType and assigneeId, and use status: "notStarted" for an active task.
• (Optional) Update or archive the form submission with PATCH /form-submissions/{formSubmissionId} as needed.
• (Optional) Reassign the form using the assignedTo field. Notifications are only sent to new assignees for forms with a status of notStarted, inProgress, or changesRequested. Users do not have access to completed forms from the mobile app. If reassigning, we recommend also updating the status to a state that makes sense.

This workflow ensures your teams can receive, complete, and submit the forms assigned to them, with any necessary information already populated—minimizing manual entry and potential errors.