---
title: "Create a form submission."
method: POST
path: "/form-submissions"
tags: ["Forms"]
---

# Create a form submission.

`POST /form-submissions`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/form-submissions`
- Auth: HTTP bearer

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.

 <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Write Form Submissions** under the Forms category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Request body

- FormSubmissionsPostFormSubmissionRequestBody: Form submission fields to create.
  - `assignedTo` FormSubmissionRequestAssignedToRequestBody: Form submission assignee update object
    - `id` string, required: ID of the form submission assignee.
    - `type` 'driver' | 'user', required: Type of the form submission assignee. Valid values: `driver`, `user`
  - `dueAtTime` string, date-time: Due date of the form submission. UTC timestamp in RFC 3339 format.
  - `fields` FormSubmissionRequestFieldInputObjectRequestBody[]: List of field inputs in a form submission.
    - `assetValue` FormSubmissionRequestAssetValueObjectRequestBody: The value of an asset form input field. Only valid for asset form input fields.
      - `asset` FormSubmissionRequestAssetObjectRequestBody, required: Asset object.
        - `id` string, required: Samsara ID of the asset.
    - `barcodeValue` FormSubmissionRequestBarcodeValueObjectRequestBody: The value of a barcode form input field. Only valid for barcode form input fields.
      - `barcodes` FormSubmissionRequestBarcodeObjectRequestBody[], required: List of barcode entries.
        - `value` string, required: The captured barcode value.
    - `checkBoxesValue` FormSubmissionRequestCheckBoxesValueObjectRequestBody: The value of a check boxes form input field. Only valid for check boxes form input fields.
      - `valueIds` string[], required
    - `dateTimeValue` FormSubmissionRequestDateTimeValueObjectRequestBody: The value of a datetime form input field. Only valid for datetime form input fields.
      - `value` string, date-time, required: The value of the user generated date/time field response. UTC timestamp in RFC 3339 format.
    - `geofenceValue` FormSubmissionRequestGeofenceValueObjectRequestBody: The value of a geofence form input field. Only valid for geofence form input fields.
      - `geofence` FormSubmissionRequestGeofenceObjectRequestBody, required: Geofence object.
        - `id` string, required: Samsara ID of the geofence.
    - `id` string, uuid, required: ID of the forms input field object.
    - `mediaValue` FormSubmissionRequestMediaValueObjectRequestBody: The value of a media form input field. Only valid for media form input fields.
      - `mediaList` FormSubmissionRequestMediaItemObjectRequestBody[], required: List of media items.
        - `base64Payload` string, required: Base64-encoded binary content of the media.
        - `mediaType` string, required: MIME type of the media.
    - `multipleChoiceValue` FormSubmissionRequestMultipleChoiceValueObjectRequestBody: The value of a multiple choice form input field. Only valid for multiple choice form input fields.
      - `valueId` string, uuid, required
    - `numberValue` FormSubmissionRequestNumberValueObjectRequestBody: The value of a number form input field. Only valid for number form input fields.
      - `value` number, double, required
    - `personValue` FormSubmissionRequestPersonValueObjectRequestBody: The value of an person form input field. Only valid for person form input fields.
      - `person` FormSubmissionRequestPersonObjectRequestBody, required: Person object.
        - `polymorphicUserId` string, required: Samsara polymorphicUserID of the person.
    - `tableValue` FormSubmissionRequestTableValueObjectRequestBody: The value of a table form input field. Only valid for table form input fields.
      - `rows` FormSubmissionRequestTableRowObjectRequestBody[], required: List of rows in the table.
        - `cells` FormSubmissionRequestTableCellObjectRequestBody[], required: List of cells in the row.
          - `barcodeValue` FormSubmissionRequestBarcodeValueObjectRequestBody: The value of a barcode form input field. Only valid for barcode form input fields.
            - `barcodes` FormSubmissionRequestBarcodeObjectRequestBody[], required: List of barcode entries.
              - …
          - `checkBoxesValue` FormSubmissionRequestCheckBoxesValueObjectRequestBody: The value of a check boxes form input field. Only valid for check boxes form input fields.
            - `valueIds` string[], required
          - `dateTimeValue` FormSubmissionRequestDateTimeValueObjectRequestBody: The value of a datetime form input field. Only valid for datetime form input fields.
            - `value` string, date-time, required: The value of the user generated date/time field response. UTC timestamp in RFC 3339 format.
          - `id` string, uuid, required: Unique identifier for the cell.
          - `multipleChoiceValue` FormSubmissionRequestMultipleChoiceValueObjectRequestBody: The value of a multiple choice form input field. Only valid for multiple choice form input fields.
            - `valueId` string, uuid, required
          - `numberValue` FormSubmissionRequestNumberValueObjectRequestBody: The value of a number form input field. Only valid for number form input fields.
            - `value` number, double, required
          - `personValue` FormSubmissionRequestPersonValueObjectRequestBody: The value of an person form input field. Only valid for person form input fields.
            - `person` FormSubmissionRequestPersonObjectRequestBody, required: Person object.
              - …
          - `textValue` FormSubmissionRequestTextValueObjectRequestBody: The value of a text form input field. Only valid for text form input fields.
            - `value` string, required
          - `type` 'number' | 'text' | 'multiple_choice' | 'check_boxes' | 'datetime' | 'person' | 'barcode', required: Type of the cell field. Valid values: `number`, `text`, `multiple_choice`, `check_boxes`, `datetime`, `person`, `barcode`
        - `id` string, uuid, required: Unique identifier for the row.
    - `textValue` FormSubmissionRequestTextValueObjectRequestBody: The value of a text form input field. Only valid for text form input fields.
      - `value` string, required
    - `type` 'number' | 'text' | 'multiple_choice' | 'check_boxes' | 'datetime' | 'asset' | 'person' | 'table' | 'geofence' | 'barcode' | 'media', required: Type of the field. Valid values: `number`, `text`, `multiple_choice`, `check_boxes`, `datetime`, `asset`, `person`, `table`, `geofence`, `barcode`, `media`
  - `formTemplate` FormTemplateRequestObjectRequestBody, required: Form template request object.
    - `id` string, uuid, required: ID of the form template.
    - `revisionId` string, uuid: ID of the form template revision. Defaults to the latest template revision if not provided
  - `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`.
  - `routeStopId` string: ID of the route stop the form submission is assigned to. Must be a unique Samsara ID.
  - `status` 'notStarted', required: Status of the form submission. Valid values: `notStarted`
  - `title` string: Title of the form submission.

## Response `200`

OK response.

- FormSubmissionsPostFormSubmissionResponseBody
  - `data` FormSubmissionResponseObjectResponseBody, required: Form Submission response object.
    - `approvalDetails` FormsProductSubmissionApprovalDetailsObjectResponseBody: The value of the approval details for a forms product submission.
      - `comment` string, required: Comment from the approver when requesting changes or approving the submission.
    - `asset` FormsAssetObjectResponseBody: Tracked or untracked (i.e. manually entered) asset object.
      - `entryType` 'tracked' | 'untracked', required: The type of entry for the asset. Valid values: `tracked`, `untracked`
      - `externalIds` object: A map of external ids
      - `id` string: ID of a tracked asset. Included if 'entryType' is `tracked`.
      - `name` string: Name of an untracked (i.e. manually entered) asset.
    - `assignedAtTime` string, date-time: Assignment time of the form submission. Sometimes returned if the submission was assigned to a user or driver. UTC timestamp in RFC 3339 format.
    - `assignedTo` FormsPolymorphicUserObjectResponseBody: User or driver object.
      - `id` string, required: ID of the polymorphic user.
      - `type` 'driver' | 'user', required: The type of the polymorphic user. Valid values: `driver`, `user`
    - `createdAtTime` string, date-time, required: Creation time of the form submission. UTC timestamp in RFC 3339 format.
    - `dueAtTime` string, date-time: Time of when the submission is due. Sometimes returned, if the submission has a due date. UTC timestamp in RFC 3339 format.
    - `durationMs` integer: Duration between when the form submission was started on the client and submitted, in milliseconds. Omitted until the form is actually submitted or when the client start timestamp was not recorded.
    - `externalIds` object: A map of external ids
    - `fields` FormsFieldInputObjectResponseBody[], required: List of field inputs in a form submission.
      - `assetValue` FormsAssetValueObjectResponseBody: The value of an asset form input field.
        - `asset` FormsAssetObjectResponseBody, required: Tracked or untracked (i.e. manually entered) asset object.
          - `entryType` 'tracked' | 'untracked', required: The type of entry for the asset. Valid values: `tracked`, `untracked`
          - `externalIds` object: A map of external ids
          - `id` string: ID of a tracked asset. Included if 'entryType' is `tracked`.
          - `name` string: Name of an untracked (i.e. manually entered) asset.
      - `barcodeValue` FormsBarcodeValueObjectResponseBody: The value of a barcode form input field.
        - `barcodes` FormsBarcodeObjectResponseBody[], required: List of barcode entries.
          - `value` string, required: The captured barcode value.
      - `checkBoxesValue` FormsCheckBoxesValueObjectResponseBody: The value of a check boxes form input field.
        - `value` string[], required: List of selected options.
        - `valueIds` string[], required: List of selected option IDs.
      - `dateTimeValue` FormsDateTimeValueObjectResponseBody: The value of a datetime form input field.
        - `dateValue` string, date: Calendar date in YYYY-MM-DD format in the stored field timezone. Present when type is `date` (date-only fields).
        - `type` 'datetime' | 'date' | 'time', required: The type of datetime format. Valid values: `datetime`, `date`, `time`
        - `value` string, date-time, required: UTC timestamp in RFC 3339 format.
      - `geofenceValue` FormsGeofenceValueObjectResponseBody: The value of a geofence form input field.
        - `geofence` FormsGeofenceObjectResponseBody, required: Tracked or untracked (i.e. manually entered) geofence object.
          - `address` string: Address of the geofence. Included if 'entryType' is `tracked`.
          - `entryType` 'tracked' | 'untracked', required: The type of entry for the geofence. Valid values: `tracked`, `untracked`
          - `externalIds` object: A map of external ids
          - `id` string: ID of the tracked geofence. Included if 'entryType' is `tracked`.
          - `name` string: Name of an untracked (i.e. manually entered) geofence.
      - `id` string, uuid, required: ID of the forms input field object.
      - `issue` FormsIssueCreatedByFieldObjectResponseBody: Issue created from this form input field input object.
        - `externalIds` object: A map of external ids
        - `id` string, required: ID of the issue created from this form input field input object.
      - `label` string: Forms input field label.
      - `mediaList` FormsMediaRecordObjectResponseBody[]: List of forms media record objects.
        - `id` string, uuid, required: ID of the media record.
        - `processingStatus` 'unknown' | 'processing' | 'finished', required: Status of the media record. Valid values: `unknown`, `processing`, `finished`
        - `url` string, uri: URL containing a link to associated media content. Included if 'processingStatus' is 'finished'.
        - `urlExpiresAt` string, date-time: Expiration time of the media record 'url'. UTC timestamp in RFC 3339 format.
      - `mediaValue` FormsMediaValueObjectResponseBody: The value of a media form input field.
        - `mediaList` FormsMediaRecordObjectResponseBody[], required: List of forms media record objects.
          - `id` string, uuid, required: ID of the media record.
          - `processingStatus` 'unknown' | 'processing' | 'finished', required: Status of the media record. Valid values: `unknown`, `processing`, `finished`
          - `url` string, uri: URL containing a link to associated media content. Included if 'processingStatus' is 'finished'.
          - `urlExpiresAt` string, date-time: Expiration time of the media record 'url'. UTC timestamp in RFC 3339 format.
      - `multipleChoiceValue` FormsMultipleChoiceValueObjectResponseBody: The value of a multiple choice form input field.
        - `value` string, required: Selected option.
        - `valueId` string, required: ID of the selected option.
      - `note` string: A note attached to the field input.
      - `numberValue` FormsNumberValueObjectResponseBody: The value of a number form input field.
        - `value` number, double, required: Number value.
      - `personValue` FormsPersonValueObjectResponseBody: The value of a person form input field.
        - `person` FormsPersonObjectResponseBody, required: Tracked or untracked (i.e. manually entered) person object.
          - `entryType` 'tracked' | 'untracked', required: The type of entry for the person. Valid values: `tracked`, `untracked`
          - `name` string: Name of an untracked (i.e. manually entered) person.
          - `polymorphicUserId` FormsPolymorphicUserObjectResponseBody: User or driver object.
            - `id` string, required: ID of the polymorphic user.
            - `type` 'driver' | 'user', required: The type of the polymorphic user. Valid values: `driver`, `user`
      - `signatureValue` FormsSignatureValueObjectResponseBody: The value of a signature form input field.
        - `media` FormsMediaRecordObjectResponseBody, required: Forms media record object.
          - `id` string, uuid, required: ID of the media record.
          - `processingStatus` 'unknown' | 'processing' | 'finished', required: Status of the media record. Valid values: `unknown`, `processing`, `finished`
          - `url` string, uri: URL containing a link to associated media content. Included if 'processingStatus' is 'finished'.
          - `urlExpiresAt` string, date-time: Expiration time of the media record 'url'. UTC timestamp in RFC 3339 format.
      - `tableValue` FormsTableValueObjectResponseBody: The value of a table form input field.
        - `columns` FormsTableColumnObjectResponseBody[], required: List of table columns.
          - `id` string, uuid, required: Unique identifier for the column.
          - `label` string, required: Label of the column.
          - `type` 'text' | 'number' | 'datetime' | 'check_boxes' | 'multiple_choice' | 'signature' | 'media' | 'person' | 'barcode', required: Type of the column field. Valid values: `text`, `number`, `datetime`, `check_boxes`, `multiple_choice`, `signature`, `media`, `person`, `barcode`
        - `rows` FormsTableRowObjectResponseBody[], required: List of table rows.
          - `cells` FormsTableCellObjectResponseBody[], required: List of cells in the row.
            - `barcodeValue` FormsBarcodeValueObjectResponseBody: The value of a barcode form input field.
              - …
            - `checkBoxesValue` FormsCheckBoxesValueObjectResponseBody: The value of a check boxes form input field.
              - …
            - `dateTimeValue` FormsDateTimeValueObjectResponseBody: The value of a datetime form input field.
              - …
            - `id` string, uuid, required: Unique identifier for the cell.
            - `mediaValue` FormsMediaValueObjectResponseBody: The value of a media form input field.
              - …
            - `multipleChoiceValue` FormsMultipleChoiceValueObjectResponseBody: The value of a multiple choice form input field.
              - …
            - `numberValue` FormsNumberValueObjectResponseBody: The value of a number form input field.
              - …
            - `personValue` FormsPersonValueObjectResponseBody: The value of a person form input field.
              - …
            - `signatureValue` FormsSignatureValueObjectResponseBody: The value of a signature form input field.
              - …
            - `textValue` FormsTextValueObjectResponseBody: The value of a text form input field.
              - …
            - `type` 'number' | 'text' | 'multiple_choice' | 'check_boxes' | 'datetime' | 'signature' | 'media' | 'person' | 'barcode', required: Type of the cell field. Valid values: `number`, `text`, `multiple_choice`, `check_boxes`, `datetime`, `signature`, `media`, `person`, `barcode`
          - `id` string, uuid, required: Unique identifier for the row.
      - `textValue` FormsTextValueObjectResponseBody: The value of a text form input field.
        - `value` string, required: Text value.
      - `type` 'number' | 'text' | 'multiple_choice' | 'check_boxes' | 'datetime' | 'signature' | 'media' | 'asset' | 'table' | 'person' | 'geofence' | 'barcode', required: Type of the field. Valid values: `number`, `text`, `multiple_choice`, `check_boxes`, `datetime`, `signature`, `media`, `asset`, `table`, `person`, `geofence`, `barcode`
    - `formTemplate` FormTemplateReferenceObjectResponseBody, required: Form template reference object.
      - `id` string, uuid, required: ID of the form template.
      - `revisionId` string, uuid, required: ID of the form template revision.
    - `geofence` FormsGeofenceObjectResponseBody: Tracked or untracked (i.e. manually entered) geofence object.
      - `address` string: Address of the geofence. Included if 'entryType' is `tracked`.
      - `entryType` 'tracked' | 'untracked', required: The type of entry for the geofence. Valid values: `tracked`, `untracked`
      - `externalIds` object: A map of external ids
      - `id` string: ID of the tracked geofence. Included if 'entryType' is `tracked`.
      - `name` string: Name of an untracked (i.e. manually entered) geofence.
    - `id` string, required: ID of the form submission.
    - `isRequired` boolean, required: Indicates whether the worker is required to complete this form or not. Always returned.
    - `location` FormsLocationObjectResponseBody: Form template location object.
      - `latitude` number, double, required: Latitude of a location.
      - `longitude` number, double, required: Longitude of a location.
    - `routeId` string: ID of the route. Sometimes returned if the submission was assigned to a route stop.
    - `routeStopId` string: ID of the route stop. Sometimes returned if the submission was assigned to a route stop.
    - `score` FormsScoreObjectResponseBody: Forms score object.
      - `maxPoints` number, double, required: Total possible points of the form submission.
      - `scorePercent` number, double, required: Percentage score of the form submission, calculated as scorePoints / maxPoints.
      - `scorePoints` number, double, required: Score, in points, of the form submission.
    - `status` 'notStarted' | 'completed' | 'archived' | 'inProgress' | 'needsReview' | 'changesRequested' | 'approved' | 'denied', required: State for the Form Submission. Always returned. Valid values: `notStarted`, `completed`, `archived`, `inProgress`, `needsReview`, `changesRequested`, `approved`, `denied`
    - `submittedAtTime` string, date-time, required: Submission time of the form submission. UTC timestamp in RFC 3339 format.
    - `submittedBy` FormsPolymorphicUserObjectResponseBody, required: User or driver object.
      - `id` string, required: ID of the polymorphic user.
      - `type` 'driver' | 'user', required: The type of the polymorphic user. Valid values: `driver`, `user`
    - `title` string: Title of the form submission. Sometimes returned if the submission has a title.
    - `updatedAtTime` string, date-time, required: Update time of the form submission. UTC timestamp in RFC 3339 format.

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)