[beta] Create a form submission.

post https://api.samsara.com/form-submissions

Creates a form submission.

Beta: This endpoint is in beta and is likely to change before being broadly available. Reach out to your Samsara Representative to have Forms APIs enabled for your organization.

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

To use this endpoint, select Write Form Submissions under the Closed Beta 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.

Body Params

assignedTo

object

Form submission assignee update object

dueAtTime

date-time

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

fields

array of objects

List of field inputs in a form submission.

fields

formTemplate

object

required

Form template reference object.

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

string

required

Status of the form submission. Valid values: notStarted

title

string

length ≤ 255

Title of the form submission.

Responses

Response body

object

data

object

required

Form Submission response object.

asset

object

Tracked or untracked (i.e. manually entered) asset object.

assignedAtTime

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

object

User or driver object.

createdAtTime

date-time

required

Creation time of the form submission. UTC timestamp in RFC 3339 format.

dueAtTime

date-time

Time of when the submission is due. Sometimes returned, if the submission has a due date. UTC timestamp in RFC 3339 format.

externalIds

object

A map of external ids

Has additional fields

fields

array of objects

required

List of field inputs in a form submission.

fields*

object

assetValue

object

The value of an asset form input field.

checkBoxesValue

object

The value of a check boxes form input field.

dateTimeValue

object

The value of a datetime form input field.

string

required

ID of the forms input field object.

issue

object

Issue created from this form input field input object.

label

string

Forms input field label.

mediaList

array of objects

List of forms media record objects.

mediaList

object

string

required

ID of the media record.

processingStatus

string

required

Status of the media record. Valid values: unknown, processing, finished

unknown processing finished

url

uri

URL containing a link to associated media content. Included if 'processingStatus' is 'finished'.

urlExpiresAt

date-time

Expiration time of the media record 'url'. UTC timestamp in RFC 3339 format.

mediaValue

object

The value of a media form input field.

multipleChoiceValue

object

The value of a multiple choice form input field.

note

string

A note attached to the field input.

numberValue

object

The value of a number form input field.

personValue

object

The value of a person form input field.

signatureValue

object

The value of a signature form input field.

tableValue

object

The value of a table form input field.

textValue

object

The value of a text form input field.

type

string

required

Type of the field. Valid values: number, text, multiple_choice, check_boxes, datetime, signature, media, asset, table

number, text, multiple_choice, check_boxes, datetime, signature, media, asset, table

formTemplate

object

required

Form template reference object.

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

object

Form template location object.

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

object

Forms score object.

status

string

required

State for the Form Submission. Always returned. Valid values: notStarted, completed, archived, inProgress, needsReview, changesRequested, approved

notStarted completed archived inProgress needsReview changesRequested approved

submittedAtTime

date-time

required

Submission time of the form submission. UTC timestamp in RFC 3339 format.

submittedBy

object

required

User or driver object.

title

string

Title of the form submission. Sometimes returned if the submission has a title.

updatedAtTime

date-time

required

Update time of the form submission. UTC timestamp in RFC 3339 format.

Language

Credentials

Bearer

URL


xxxxxxxxxx
12
1
curl --request POST \
2
     --url https://api.samsara.com/form-submissions \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "assignedTo": {
8
    "type": "driver"
9
  },
10
  "status": "notStarted"
11
}
12
'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200OK response.

401Unauthorized response.

404Not Found response.

405Method Not Allowed response.

429Too Many Requests response.

500Internal Server Error response.

501Not Implemented response.

502Bad Gateway response.

503Service Unavailable response.

504Gateway Timeout response.

defaultBad Request response.