Forms With Tables

Pre-populate Samsara form submissions that include table fields with structured row and column data.

Learn to use Samsara’s API to pre-populate forms that include table fields. You will learn how to:

1. Fetch a form template that includes a table field.
2. Create a form submission with a table field pre-filled with data.

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. Fetch the form template

   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.

   curl --location 'https://api.samsara.com/form-templates' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer YOUR_API_TOKEN'
   

   The response includes the template’s fields array. Within it, a table field has "type": "table" and a unique id. Each column inside the table specifies its own id, label, and type (such as number, text, multiple_choice, check_boxes, datetime, signature, media, or person).

   For example, a Forklift Inspection template might define a table with these columns:

   {
     "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" }
         ]
       }
     ]
   }
   

   Understanding the table field in the template

   • "type": "table": Indicates this is a table field.
   • The table’s id: 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-populate 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.

   Note the key points:

   1. Use the table’s id from the template in the fields array.
   2. Set each row’s id to the table field’s id (repeated for each row).
   3. Cells: An array of fields representing each column in that row.

   curl --location 'https://api.samsara.com/form-submissions' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer YOUR_API_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" }
                 }
               ]
             }
           ]
         }
       }
     ]
   }'
   

Key points

1. Row id must be set to the table field’s id in every row you include.
2. Columns are effectively “fields within the table.” Their id and type in the submission must match what’s defined in the template.
3. Partial row data is possible by omitting the cell entirely for that column.
4. Pre-population in a submission is similar to filling other fields, except you nest them under a tableValue.rows[].cells[] structure.