Create and assign forms
Digitize forms, build workflows, and automate processes for safer, more efficient operations.
Beta
Form API endpoints are in beta. Please reach out to your account team to enable them for your organization.
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.
Note: 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.
Example request
curl --location 'https://api.samsara.com/form-templates'
--header 'Accept: application/json'
--header 'Authorization: <TOKEN>'
Example response
{
"data": [
{
"id": "456461",
"revisionId": "567572",
"createdAtTime": "1976-03-06T08:22:53Z",
"updatedAtTime": "1976-03-06T08:22:53Z",
"createdBy": {
"id": "24005",
"type": "user"
},
"updatedBy": {
"id": "24005",
"type": "user"
},
"title": "Forklift Inspection",
"description": "Inspection used daily by all operators",
"fields": [
{
"id": "12345",
"isRequired": true,
"label": "Engine Hours",
"type": "number",
"numDecimalPlaces": 0
},
{
"id": "12346",
"isRequired": true,
"label": "Make Model Year",
"type": "text"
},
{
"id": "12347",
"isRequired": false,
"label": "Job #",
"type": "text"
},
{
"id": "12348",
"isRequired": true,
"label": "Seat belt is working",
"type": "multiple_choice",
"questionWeight": 3,
"options": [
{
"label": "Good",
"id": "e879028d-bce5-0238-ffec-11cd9236bcda",
"ignoreQuestionFromScoreIfSelected": false,
"optionScoreWeight": 3
},
{
"label": "Poor",
"id": "5371827f-367a-8992-d117-b30906de18bd",
"ignoreQuestionFromScoreIfSelected": false,
"optionScoreWeight": 2
},
{
"label": "N/A",
"id": "075b7e48-d3f2-0f0e-fa2f-3d76298afc02",
"ignoreQuestionFromScoreIfSelected": true,
"optionScoreWeight": 0
}
]
},
{
"id": "12349",
"isRequired": true,
"label": "Hazards identified",
"type": "check_boxes",
"options": [
{
"label": "Oil spill",
"id": "e879028d-bce5-0238-ffec-11cd9236bcda"
},
{
"label": "Fire",
"id": "5371827f-367a-8992-d117-b30906de18bd"
},
{
"label": "Electricity",
"id": "075b7e48-d3f2-0f0e-fa2f-3d76298afc02"
}
]
},
{
"id": "12350",
"isRequired": false,
"label": "Photo",
"type": "media"
},
{
"id": "12351",
"isRequired": true,
"label": "Hazard identified date time",
"type": "datetime",
"allowedDateTimeValueType": "time"
},
{
"id": "12352",
"isRequired": true,
"label": "Sign here",
"type": "signature",
"legalText": "I consent to using electronic signatures in this transaction."
},
{
"id": "12353",
"isRequired": true,
"label": "Asset #",
"allowedAssetTypes": [
"vehicle"
]
},
{
"id": "12354",
"isRequired": true,
"label": "Address #",
"type": "geofence"
},
{
"id": "12355",
"isRequired": true,
"label": "User 1",
"type": "person",
"allowManualEntry": true,
"includeDrivers": true,
"includeUsers": true,
"filterByRoleIds": [
"23d4d8d3-dc10-4e7a-a183-69968751f23e"
],
"filterByCurrentDriverTags": false
},
{
"id": "12356",
"isRequired": true,
"label": "Follow these instructions",
"type": "instruction"
},
{
"id": "12357",
"isRequired": true,
"label": "Video",
"type": "media_instruction"
},
{
"id": "123458",
"isRequired": true,
"type": "table",
"columns": [
{
"id": "field-uuid-store-number",
"label": "Store Number",
"type": "number"
},
{
"id": "field-uuid-city",
"label": "City",
"type": "text"
},
{
"id": "field-uuid-store-number-if-delivered",
"label": "Delivered?",
"type": "multiple_choice",
"options": [
{
"label": "Yes",
"id": "e879028d-bce5-0238-ffec-11cd9236abcd"
},
{
"label": "No",
"id": "5371827f-367a-8992-d117-b30906de18db"
}
]
},
{
"id": "field-uuid-dropoff-location",
"label": "Dropoff location",
"type": "check_boxes",
"options": [
{
"label": "Location 1",
"id": "e879028d-bce5-0238-ffec-11cd9236bcda"
},
{
"label": "Location 2",
"id": "5371827f-367a-8992-d117-b30906de18bd"
},
{
"label": "Location 3",
"id": "075b7e48-d3f2-0f0e-fa2f-3d76298afc02"
}
]
},
{
"id": "field-uuid-date",
"label": "Dropoff Date",
"type": "datetime",
"allowedDateTimeValueType": "time"
},
{
"id": "field-uuid-signature",
"label": "Signature",
"type": "signature"
},
{
"id": "field-uuid-photo",
"label": "Proof of Delivery",
"type": "media"
},
{
"id": "field-uuid-person",
"label": "Delivered By",
"type": "person",
"allowManualEntry": true,
"includeDrivers": true,
"includeUsers": true,
"filterByRoleUuids": [
"23d4d8d3-dc10-4e7a-a183-69968751f23e"
],
"filterByCurrentDriverTags": false
}
]
}
],
"sections": [
{
"label": "Section 1",
"fieldIndexFirstInclusive": 0,
"fieldIndexLastInclusive": 6
},
{
"label": "Section 2",
"fieldIndexFirstInclusive": 7,
"fieldIndexLastInclusive": 11
}
],
"approvalConfig": {
"type": "singleApproval",
"allowManualApproverSelection": true,
"singleApprovalConfig": {
"requirements": {
"roleIds": [
"68004a16-be3c-4ef6-b15a-1c45a2c27a92",
"75711d33-dbcf-490c-aa34-f9d60122635"
]
}
}
}
}
],
"pagination": {
"endCursor": "...",
"hasNextPage": true
}
}
Identify the template you want workers to fill out by id.
Note: 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 our Form Field Types guide.
2. Create and assign a form submission
Either a routeStopId or an assignedTo worker are 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 stay in lock step.
Use 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 shows how to create a new form submission for the template with ID 9e118726-41e2-5ba9-8c1a-eb78e8a391ac and its revision with ID 889fd3ae-b378-452a-b7b7-4b9a86cac4d9. The form submission is assigned to driver with ID 52514325. 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.
Example request
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"
}
}'
Example response
{
"data": {
"id": "659fc0b2-4454-4662-a186-f5b81ca9f15c",
"formTemplate": {
"id": "9e118726-41e2-5ba9-8c1a-eb78e8a391ac",
"revisionId": "889fd3ae-b378-452a-b7b7-4b9a86cac4d9"
},
"createdAtTime": "2025-02-13T20:39:38Z",
"submittedAtTime": "1970-01-01T00:00:00Z",
"updatedAtTime": "2025-02-13T20:39:38Z",
"submittedBy": {
"id": "1131135",
"type": "user"
},
"fields": [],
"assignedTo": {
"id": "52514325",
"type": "driver"
},
"status": "notStarted",
"isRequired": true
}
}
Creating and assigning a blank form to a route stop
This example shows how to create a new form submission for a template with ID 3ff41093-6da1-5d57-9cec-fa2536a03d09 and revision ID 39eeaba2-556b-4c32-9fd8-5776ba508929. Instead of assigning to a driver, the form is assigned to the route stop with ID 6118765423. By assigning the form to a route stop, the driver must submit the form before moving on from this stop.
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"
},
"createdAtTime": "2025-02-13T21:26:32Z",
"submittedAtTime": "1970-01-01T00:00:00Z",
"updatedAtTime": "2025-02-13T21:26:32Z",
"submittedBy": {
"id": "1131135",
"type": "user"
},
"fields": [],
"status": "notStarted",
"isRequired": true,
"dueAtTime": "2025-02-04T00:00:00Z",
"routeId": "6017940844",
"routeStopId": "6118765423"
}
}
Pre-populating a basic form
This example shows how to create a new pre-populated form submission. For context, this template is for a "Trailer Inspection" and has ID 3ff41093-6da1-5d57-9cec-fa2536a03d09 and revision ID 39eeaba2-556b-4c32-9fd8-5776ba508929. The form is assigned to a driver and is pre-populated with the trailer to be inspected.
The form template contains an asset field with ID 685d5c46-8118-40f4-b9d7-8fabc98ab464. 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.
"fields": [{
"id": "685d5c46-8118-40f4-b9d7-8fabc98ab464",
"type": "asset",
"assetValue": {
"asset": {
"id": "281474994182986"
}
}
}]
See the full list of Form fields for reference to understand what data is required for each field answer.
Example request
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"
}
}
}]
}'
Example response
{
"data": {
"id": "daaeb797-f50e-4834-956a-5db78a1cf17e",
"formTemplate": {
"id": "3ff41093-6da1-5d57-9cec-fa2536a03d09",
"revisionId": "39eeaba2-556b-4c32-9fd8-5776ba508929"
},
"createdAtTime": "2025-02-13T21:35:55Z",
"submittedAtTime": "1970-01-01T00:00:00Z",
"updatedAtTime": "2025-02-13T21:35:55Z",
"submittedBy": {
"id": "1131135",
"type": "user"
},
"asset": {
"id": "281474994182986",
"entryType": "tracked"
},
"fields": [
{
"id": "685d5c46-8118-40f4-b9d7-8fabc98ab464",
"label": "Trailer",
"type": "asset",
"assetValue": {
"asset": {
"id": "281474994182986",
"entryType": "tracked"
}
}
}
],
"assignedTo": {
"id": "52514325",
"type": "driver"
},
"status": "notStarted",
"isRequired": true,
"dueAtTime": "2025-02-04T00:00:00Z"
}
}
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. Editing 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.
Example request
curl --location --request PATCH 'https://api.samsara.com/form-submissions'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Bearer <TOKEN>'
--data '{
"id": "47de8234-0196-430b-800d-b49a7b604dc5",
"title": "Updated title"
}'
Reminder: 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
/form-submissions/stream endpointPeriodically 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
FormSubmitted webhook eventsSamsara 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. Note: 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. Note: Notifications are only sent to new assignees for forms with a status ofnotStarted,inProgress, orchangesRequested. 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:notStarted,inProgress, orchangesRequested.
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.
Updated 12 days ago