Create a form submission.

Creates a form submission and assigns it to an individual worker. This endpoint can be used to create an empty or partially complete form submission and assign it to a worker.

Rate limit: 100 requests/min (learn more about rate limits here).

To use this endpoint, select Write Form Submissions under the Forms category when creating or editing an API token. Learn More.

Submit Feedback: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team.

POST /form-submissions

Create a form submission.

cURL

curl --request POST \
  --url https://api.samsara.com/form-submissions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "formTemplate": {
    "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
    "revisionId": "1214a1fa-f0c6-408b-bf85-51dc3bc71ac7"
  },
  "status": "notStarted"
}
'

200

{
  "data": {
    "createdAtTime": "2019-06-13T19:08:25Z",
    "fields": [
      {
        "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
        "type": "number",
        "assetValue": {
          "asset": {
            "entryType": "tracked",
            "externalIds": {},
            "id": "281474982859091",
            "name": "trailer 123"
          }
        },
        "checkBoxesValue": {
          "value": [
            "Option A",
            "Option B"
          ],
          "valueIds": [
            "0cbbddb3-2541-4889-b4eb-92171cbfc142",
            "d33198cb-369f-4278-8120-d92d3ebf74bf"
          ]
        },
        "dateTimeValue": {
          "type": "datetime",
          "value": "2024-08-08T18:53:23Z",
          "dateValue": "2024-08-08"
        },
        "geofenceValue": {
          "geofence": {
            "entryType": "tracked",
            "address": "123 Main St, Anytown, USA 12345",
            "externalIds": {},
            "id": "1234567890",
            "name": "Geofence Name"
          }
        },
        "issue": {
          "id": "12345",
          "externalIds": {}
        },
        "label": "Engine Hours",
        "mediaList": [
          {
            "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
            "processingStatus": "processing",
            "url": "https://samsara-forms-submission-media-uploads.s3.us-west-2.amazonaws.com/123456",
            "urlExpiresAt": "2019-06-13T19:08:25Z"
          }
        ],
        "mediaValue": {
          "mediaList": [
            {
              "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
              "processingStatus": "processing",
              "url": "https://samsara-forms-submission-media-uploads.s3.us-west-2.amazonaws.com/123456",
              "urlExpiresAt": "2019-06-13T19:08:25Z"
            }
          ]
        },
        "multipleChoiceValue": {
          "value": "Yes",
          "valueId": "94096370-7228-4d83-ae5d-b20f3e45c0fc"
        },
        "note": "Fire and oil can lead to an accident.",
        "numberValue": {
          "value": 123.456
        },
        "personValue": {
          "person": {
            "entryType": "tracked",
            "name": "Jake",
            "polymorphicUserId": {
              "id": "938172",
              "type": "driver"
            }
          }
        },
        "signatureValue": {
          "media": {
            "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
            "processingStatus": "processing",
            "url": "https://samsara-forms-submission-media-uploads.s3.us-west-2.amazonaws.com/123456",
            "urlExpiresAt": "2019-06-13T19:08:25Z"
          }
        },
        "tableValue": {
          "columns": [
            {
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
              "label": "Store Number",
              "type": "number"
            }
          ],
          "rows": [
            {
              "cells": [
                {
                  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
                  "type": "number",
                  "checkBoxesValue": {
                    "value": [
                      "Option A",
                      "Option B"
                    ],
                    "valueIds": [
                      "0cbbddb3-2541-4889-b4eb-92171cbfc142",
                      "d33198cb-369f-4278-8120-d92d3ebf74bf"
                    ]
                  },
                  "dateTimeValue": {
                    "type": "datetime",
                    "value": "2024-08-08T18:53:23Z",
                    "dateValue": "2024-08-08"
                  },
                  "mediaValue": {
                    "mediaList": [
                      {
                        "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
                        "processingStatus": "processing",
                        "url": "https://samsara-forms-submission-media-uploads.s3.us-west-2.amazonaws.com/123456",
                        "urlExpiresAt": "2019-06-13T19:08:25Z"
                      }
                    ]
                  },
                  "multipleChoiceValue": {
                    "value": "Yes",
                    "valueId": "94096370-7228-4d83-ae5d-b20f3e45c0fc"
                  },
                  "numberValue": {
                    "value": 123.456
                  },
                  "personValue": {
                    "person": {
                      "entryType": "tracked",
                      "name": "Jake",
                      "polymorphicUserId": {
                        "id": "938172",
                        "type": "driver"
                      }
                    }
                  },
                  "signatureValue": {
                    "media": {
                      "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
                      "processingStatus": "processing",
                      "url": "https://samsara-forms-submission-media-uploads.s3.us-west-2.amazonaws.com/123456",
                      "urlExpiresAt": "2019-06-13T19:08:25Z"
                    }
                  },
                  "textValue": {
                    "value": "Exposed wires"
                  }
                }
              ],
              "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
            }
          ]
        },
        "textValue": {
          "value": "Exposed wires"
        }
      }
    ],
    "formTemplate": {
      "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
      "revisionId": "1214a1fa-f0c6-408b-bf85-51dc3bc71ac7"
    },
    "id": "9814a1fa-f0c6-408b-bf85-51dc3bc71ac7",
    "isRequired": true,
    "status": "notStarted",
    "submittedAtTime": "2019-06-13T19:08:25Z",
    "submittedBy": {
      "id": "938172",
      "type": "driver"
    },
    "updatedAtTime": "2019-06-13T19:08:25Z",
    "approvalDetails": {
      "comment": "Requesting some changes to the submission."
    },
    "asset": {
      "entryType": "tracked",
      "externalIds": {},
      "id": "281474982859091",
      "name": "trailer 123"
    },
    "assignedAtTime": "2019-06-13T19:08:25Z",
    "assignedTo": {
      "id": "938172",
      "type": "driver"
    },
    "dueAtTime": "2019-06-13T19:08:25Z",
    "externalIds": {},
    "geofence": {
      "entryType": "tracked",
      "address": "123 Main St, Anytown, USA 12345",
      "externalIds": {},
      "id": "1234567890",
      "name": "Geofence Name"
    },
    "location": {
      "latitude": 12333122.3,
      "longitude": 1233331.4
    },
    "routeId": "123456789",
    "routeStopId": "987654321",
    "score": {
      "maxPoints": 80,
      "scorePercent": 75,
      "scorePoints": 60
    },
    "title": "Form Submission Title"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Form submission fields to create.

formTemplate · object · required

Form template request object.

Show child attributes

status · enum<string> · required

Status of the form submission. Valid values: notStarted

Available options: notStarted

Example:

"notStarted"

assignedTo · object

Form submission assignee update object

Show child attributes

dueAtTime · string<date-time>

Due date of the form submission. UTC timestamp in RFC 3339 format.

Example:

"2019-06-13T19:08:25Z"

fields · object[]

List of field inputs in a form submission.

Show child attributes

isRequired · boolean

Indicates whether the worker is required to complete this form or not at a specific route stop. Defaults to true if the form is assigned to a user or driver. When true, the worker cannot depart the route stop until this form submission is submitted.

Example:

true

routeStopId · string

ID of the route stop the form submission is assigned to. Must be a unique Samsara ID.

Example:

"4070621712"

title · string

Title of the form submission.

Maximum string length: 255

Example:

"Job - J999"

Response

200

application/json

OK response.

data · object · required

Form Submission response object.

Show child attributes