Forms with tables
Working with form submissions when a form template has a table field
Beta
Form API endpoints are in beta. Please reach out to your account team to enable them for your organization.
Learn to use Samsara's API to pre-populate forms that include table fields. You will learn how to:
-
Fetch a form template that includes a table field.
-
Create a form submission with a table field pre-filled with data.
Note: This guide assumes you are already familiar with the basics of creating form submissions and the overall Form Submissions API. If you are new to working with forms, see the Create and assign forms guide first.
Table fields
A table field in a Samsara form template allows you to gather multiple pieces of structured data in a grid-like format.
Each table has:
- Columns that define the Field Type (e.g.,
text,number,multiple_choice) and label. - Rows that represent individual data entries submitted in the form.
When you fetch a form template, table fields will appear in the template's fields array with "type": "table". Each table field has its own unique id (UUID) and an internal definition for its columns.
When creating a form submission with a table, supply an array of rows containing the data for each row. The ID of the row must match the ID of the table field.
This form template includes a table for tracking the Order ID and whether the order was received in good condition.
Examples below show how to use the API to pre-populate order IDs into the table so that workers can submit forms with the order ID cells pre-filled.
1. Fetching the form template
COMING SOON: The API to fetch form templates is coming soon.
To see the structure of a table field (including its columns) and plan how you will submit data, you need to fetch the form template.
Example request
curl --location 'https://api.samsara.com/form-templates'
--header 'Accept: application/json'
--header 'Authorization: <TOKEN>'
Example response
{
"data": [
{
"id": "456461",
"revisionId": "567572",
"createdAtTime": "1976-03-06T08:22:53Z",
"updatedAtTime": "1976-03-06T08:22:53Z",
"createdBy": {
"id": "24005",
"type": "user"
},
"updatedBy": {
"id": "24005",
"type": "user"
},
"title": "Forklift Inspection",
"description": "Inspection used daily by all operators",
"fields": [
{
"id": "feec3415-0f17-4dab-8588-ac4e3a60fec5",
"isRequired": true,
"type": "table",
"columns": [
{
"id": "field-uuid-store-number",
"label": "Store Number",
"type": "number"
},
{
"id": "field-uuid-city",
"label": "City",
"type": "text"
},
{
"id": "field-uuid-store-number-if-delivered",
"label": "Delivered?",
"type": "multiple_choice",
"options": [
{
"label": "Yes",
"id": "e879028d-bce5-0238-ffec-11cd9236abcd"
},
{
"label": "No",
"id": "5371827f-367a-8992-d117-b30906de18db"
}
]
},
{
"id": "field-uuid-dropoff-location",
"label": "Dropoff location",
"type": "check_boxes",
"options": [
{
"label": "Location 1",
"id": "e879028d-bce5-0238-ffec-11cd9236bcda"
},
{
"label": "Location 2",
"id": "5371827f-367a-8992-d117-b30906de18bd"
},
{
"label": "Location 3",
"id": "075b7e48-d3f2-0f0e-fa2f-3d76298afc02"
}
]
},
{
"id": "field-uuid-date",
"label": "Dropoff Date",
"type": "datetime",
"allowedDateTimeValueType": "time"
},
{
"id": "field-uuid-signature",
"label": "Signature",
"type": "signature"
},
{
"id": "field-uuid-photo",
"label": "Proof of Delivery",
"type": "media"
},
{
"id": "field-uuid-person",
"label": "Delivered By",
"type": "person",
"allowManualEntry": true,
"includeDrivers": true,
"includeUsers": true,
"filterByRoleUuids": [
"23d4d8d3-dc10-4e7a-a183-69968751f23e"
],
"filterByCurrentDriverTags": false
}
]
}
],
"sections": [
{
"label": "Section 1",
"fieldIndexFirstInclusive": 0,
"fieldIndexLastInclusive": 6
},
{
"label": "Section 2",
"fieldIndexFirstInclusive": 7,
"fieldIndexLastInclusive": 11
}
],
"approvalConfig": {
"type": "singleApproval",
"allowManualApproverSelection": true,
"singleApprovalConfig": {
"requirements": {
"roleIds": [
"68004a16-be3c-4ef6-b15a-1c45a2c27a92",
"75711d33-dbcf-490c-aa34-f9d60122635"
]
}
}
}
}
],
"pagination": {
"endCursor": "...",
"hasNextPage": true
}
}
Understanding the table field in the template
"type": "table": Indicates this is a table field."id": "feec3415-0f17-4dab-8588-ac4e3a60fec5": The table field's unique UUID. Use this in the submission to identify which table to fill in.
This structure is required to correctly build the rows and their cells in the new form submission.
2. Pre-populating a table in a form submission
Use the Create a form submission endpoint to create a new form submission. Pre-populate the table with rows of data by including a fields array, where each table field has a tableValue property containing one or more rows.
Below is a simplified example of creating a form submission with two rows pre-filled in a single table. Note the following key points:
- Use the table’s
idfrom the template in thefieldsarray. - Set each row's
idto the table field’sid(repeated for each row). - Cells: An array of fields representing each column in that row.
Example request
curl --location 'https://api.samsara.com/form-submissions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
"formTemplate": {
"id": "9e118726-41e2-5ba9-8c1a-eb78e8a391ac",
"revisionId": "4a6d8108-9238-48c1-b8df-b16bfe0bcb39"
},
"assignedTo": {
"id": "52514325",
"type": "driver"
},
"title": "Proof of Order Delivery",
"status": "notStarted",
"fields": [
{
"id": "d873cdf8-59d9-405f-aa95-44ca56ef6f0e",
"type": "table",
"tableValue": {
"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": {
"valueId": "732d6ff1-b33e-410b-a3d9-84ddbeae0916"
}
}
]
},
{
"id": "d873cdf8-59d9-405f-aa95-44ca56ef6f0e",
"cells": [
{
"id": "75996673-3621-4f7a-93d0-edb5a3b235cf",
"type": "text",
"textValue": {
"value": "100001"
}
}
]
}
]
}
}
]
}'
Example response
{
"data": {
"id": "2da31587-1644-4952-8fb5-6ff73b0d857d",
"formTemplate": {
"id": "9e118726-41e2-5ba9-8c1a-eb78e8a391ac",
"revisionId": "4a6d8108-9238-48c1-b8df-b16bfe0bcb39"
},
"createdAtTime": "2025-02-12T19:39:22Z",
"submittedAtTime": "1970-01-01T00:00:00Z",
"updatedAtTime": "2025-02-12T19:39:22Z",
"submittedBy": {
"id": "1131135",
"type": "user"
},
"fields": [
{
"id": "d873cdf8-59d9-405f-aa95-44ca56ef6f0e",
"label": "Order Details",
"type": "table",
"tableValue": {
"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": "Yes"
}
}
]
},
{
"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"
}
]
}
]
}
}
],
"assignedTo": {
"id": "52514325",
"type": "driver"
},
"title": "Proof of Order Delivery",
"status": "notStarted",
"isRequired": true
}
}
Key points
- Row
idmust be set to the table field’sidin every row you include. - Columns are effectively “fields within the table.” Their
idandtypein the submission must match what’s defined in the template. - Partial row data is possible by omitting the cell entirely for that column.
- Pre-population in a submission is similar to filling other fields, except you nest them under a
tableValue.rows[].cells[]structure.
Updated 12 days ago