👍

Beta

Form API endpoints are in beta. Please reach out to your account team to enable them for your organization.

When a form submission is created, Samsara returns a JSON response that includes:

1. Top-Level (Default) Fields – These appear directly under the submission object (e.g., id, submittedBy, location, timestamps).
2. 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
  }
}

Media (Photo or File Upload)

Upload or capture media (images, videos, PDF, and DOCX).

Commonly used for “photo” fields.

Each form submission can handle up to 50 images total (including signatures).

{
  "id": "d93fc11f-e82c-42d1-89a9-d2909e61bf74",
  "type": "media",
  "mediaValue": {
    "mediaList": [
      {
        "id": "6a612a40-319a-4659-a989-dd8d21175b05",
				"processingStatus": "finished",
        "url": "...",
        "urlExpiresAt": "2025-02-07T21:07:19Z"
  		}
    ] 
  }
}

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

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

1. 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.”).
2. 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.
3. 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.