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
  }
}

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'sid, must match the table field'sid .

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.