Form fields
Field types enable you to capture the correct type of data needed within your Forms.
When a form submission is created, Samsara returns a JSON response that includes:
- Top-Level (Default) Fields – These appear directly under the submission object (e.g., id, submittedBy, location, timestamps).
- A
fields
array – Contains all fields (e.g., text, person, multiple choice, check boxes, table, etc.).
The fields Array
The fields array on a form submission can contain any of the fields that the related form template includes. Each field in has:
- A unique ID
- A type (e.g.,
text
,person
,multiple_choice
,table
, etc.) - A value object (like
textValue
,personValue
,multipleChoiceValue
,tableValue
, etc.)
Field Type Reference
Text
Captures freeform text (no enforced maximum length apart from the 65,535-character overall form limit).
Note: Automatically detects URLs, making them clickable in the Samsara Driver App.
{
"id": "4f8280be-4ad6-480e-8dc8-b73a15275dfd",
"type": "text",
"textValue": {
"value": "Hello, Forms"
}
}
Person
Select a user (driver or admin) in the organization.
Can be filtered by tags or roles.
Also supports an entryType
of "manual" if a user is typed in offline. The example below shows a “tracked” user with a known ID.
{
"id": "2a63da6e-4a6e-482b-bfb4-db0c6fe6b957",
"type": "person",
"personValue": {
"person": {
"polymorphicUserId": {
"id": "52559478",
"type": "driver"
},
"entryType": "tracked"
}
}
}
Datetime
This type can store a date, time, or datetime depending on how the template is configured. Unlike the default submission timestamp at the top level, these fields appear in the fields array with a dateTimeValue.
Date
{
"id": "07459cbc-9d33-4697-ad2b-f400fdc6f298",
"type": "datetime",
"dateTimeValue": {
"value": "2025-02-06T21:05:11Z",
"type": "date"
}
}
Stores only the date portion (still an ISO8601 string).
Datetime
{
"id": "39a0ef66-9fe9-4505-97a7-2b652983a424",
"type": "datetime",
"dateTimeValue": {
"value": "2025-02-06T21:05:14Z",
"type": "datetime"
}
}
Stores both date and time.
Time
{
"id": "10d54ceb-121f-4b07-a47b-5a2ab4e593fa",
"type": "datetime",
"dateTimeValue": {
"value": "2025-02-06T21:05:16Z",
"type": "time"
}
}
Stores only a time value (again in ISO8601).
Multiple Choice (Single Select)
Select exactly one of multiple predefined options (like a radio button). Can have up to 100 options.
{
"id": "d825a935-a8d1-416f-a5f8-b8100a02f763",
"type": "multiple_choice",
"multipleChoiceValue": {
"value": "Pizza"
}
}
Issue Integration: If a choice triggers an issue, you may see:
{
"id": "...",
"type": "multiple_choice",
"multipleChoiceValue": { "value": "No" },
"issue": { "id": "7af8236c-7bbb-4a17-9876-ac3531b5f372" }
}
Check Boxes (Multi Select)
Select one or more predefined options.
Like a set of checkboxes.
Min 1, max 100 options.
{
"id": "30d55ab0-7bd2-4259-8c11-a4dbdc64111c",
"type": "check_boxes",
"checkBoxesValue": {
"value": [
"Basketball",
"Baseball"
]
},
"note": "Pickleball needs to be an option"
}
Note: This sample shows an attached note. Notes can be required if the selected option triggers a requirement.
Number
Captures positive numeric values.
No maximum length by default.
Does not support negative numbers.
Can include decimals without any enforced limit on decimal places.
{
"id": "095cec05-8179-4a07-adea-6ba245e115dc",
"type": "number",
"numberValue": {
"value": 10
}
}
Asset
Select a Samsara asset (Vehicle, Trailer, Equipment, Unpowered)
One asset per form. Assets related to form submissions are surfaced at the top level of the form submission data under asset
.
{
"id": "0bde3fff-f020-4217-80b0-1ae4b4e19de2",
"label": "Trailer",
"type": "asset",
"assetValue": {
"asset": {
"id": "281474994182986",
"entryType": "tracked"
}
}
}
Signature
Draw a signature on the device.
The signature is stored as an image and is accessible via a URL with an expiration.
A maximum of 50 total images (photos + signatures) is supported per submission.
{
"id": "3ef65b28-b199-4afa-ad20-f621a2fe4496",
"type": "signature",
"signatureValue": {
"media": {
"id": "a2f0fa7c-7251-4194-8665-5ed4898be0e6",
"processingStatus": "finished",
"url": "...",
"urlExpiresAt": "2025-02-07T21:07:19Z"
}
}
}
Table
Organizes sub-fields (columns) in rows.
Each column has a type (text, multiple_choice, etc.).
Each row has matching “cells” that store user responses.
See the Forms with tables guide for more detail about working with tables.
{
"columns": [
{
"id": "75996673-3621-4f7a-93d0-edb5a3b235cf",
"label": "Order ID",
"type": "text"
},
{
"id": "4c6090b8-119c-46b9-8a2d-971c84247668",
"label": "Received in good condition?",
"type": "multiple_choice"
}
],
"rows": [
{
"id": "d873cdf8-59d9-405f-aa95-44ca56ef6f0e",
"cells": [
{
"id": "75996673-3621-4f7a-93d0-edb5a3b235cf",
"type": "text",
"textValue": {
"value": "999"
}
},
{
"id": "4c6090b8-119c-46b9-8a2d-971c84247668",
"type": "multiple_choice",
"multipleChoiceValue": {
"value": "No"
}
}
]
}
]
}
Note: Each column is defined at the template level (id
, type
, and label
), and each row’s cells match those columns. The row's id
, must match the table field's id
.
Other Field Types
Field Type | Description |
---|---|
instructions | A read-only text block, often used to guide workers. Supports rich text, truncated with “see more” for length. No user input. |
media_instructions | Similar to instructions, but for embedding images/videos (up to 3MB for images, 15MB for videos). No user input. |
photo (media) | An older approach for capturing a photo (similar to the “media” field). The user can take a photo or choose from the library. Has a max of 50 images (including signatures) per submission. |
Sections
Sections are not listed in the fields array. Sections are logical groups fields in the form template. Each section has a name, and all fields in the form are placed in at least one section.
Additional Notes
- Required Fields
- If a field is required in the template, the driver cannot submit until they’ve provided valid data.
- Some templates can require notes, images, or issues based on a field’s value (e.g., “If the driver selects ‘No,’ require an issue.”).
- Timestamps & Timezones
- submittedAtTime, createdAtTime, and updatedAtTime are always stored in UTC (ISO 8601). The dashboard or your local environment may show these times in local timezone.
- Limits
- A single form submission can include up to 50 images total (photos + signatures).
- Check box or multiple choice fields can have up to 100 options.
- The text field has a large character limit (65,535 overall, or 64KB of data) in practice.
Updated 14 days ago