Skip to navigation

Working with Tables

Table rows hold most of a document's lab data, so they are fetched separately from the parts listing. This guide covers unstructured and Results tables, how cell values evaluate, and how to insert rows and update cells.

Beta APIs

The Document APIs are beta. Send the EARLY-ACCESS: true header on every request shown here; without it these endpoints are unavailable. See Introduction to Documents and the Stability Guidelines.

Current limitations

The API reads and writes data in unstructured tables and Results tables. Support for more structured table types is in active development.

Table rows are where most document lab data lives. Because row data can be large, it is fetched separately from the list of document parts.

Documents contain two kinds of tables:

  • Unstructured tables have free-form columns, and every cell holds text.
  • Structured tables have columns defined by a schema, and each cell holds a value of its column’s type. The supported structured table type is the Results table.

Reading table data

When you list a document’s content, tables appear as summary objects. The __typename identifies the kind of table, such as DocumentPartUnstructuredTable or DocumentPartResultsTable.

Endpoint
GET /api/v3/entry/etr_8rVKW0g7/parts/items

To get the table’s columns and other details, request the table by ID.

GET /api/v3/document-part-results-table/docpart_2mWG2SPvHX

On structured tables, each column definition has a cellValueType, which sets the type of value the column accepts.

To get the rows, follow the rows URL. Rows are paginated with pageSize and nextToken.

GET /api/v3/document-part-results-table/docpart_2mWG2SPvHX/rows/items

Cell values

Two properties hold a cell’s value:

  • inputValue is the value the user or API edits. In unstructured tables it’s always a TextValue, which can hold plain text, cell references, and formulas. In structured tables its type matches the column, such as ObjectLinkValue or DecimalValue.
  • evaluationValue is what the spreadsheet evaluator outputs, and it usually matches what Benchling displays. Prefer it when reading a table, but it isn’t always available; see Evaluation.

Evaluation

Tables take part in spreadsheet evaluation. Evaluation takes each inputValue and coerces it into the standard value Benchling displays. It’s also what interprets spreadsheet references and formulas, such as =SUM(A1:A10)/6.

The table’s isEvaluated property says whether its cells have evaluationValues.

Only the browser client evaluates spreadsheets. New evaluationValues are generated only when someone edits the document in the Benchling web app. Any API edit clears the evaluated values until the document is next edited there. When you read a table right after an API write, fall back to inputValue if evaluationValue is null.

Writing table data

Tables are edited with a partsMutation on the document that contains them. The request body is the same for unstructured and structured tables.

Endpoint
PATCH /api/v3/entry/{entry_id}

Two operations edit an existing table:

  • insert_table_rows adds rows to the end of a table.
  • update_table_cells changes the value or formatting of specific cells.

Every partsMutation needs the document’s current version. It’s available as versionMetadata.versionId on the document or on any of its parts. If it doesn’t match the current version on the server, the request returns HTTP 409. Get the latest version and retry.

Inserting rows

Each new row lists the cells to fill in, and each cell targets a column by columnIndex. Columns without a cell get the column’s default value, and default formulas shift down to the new row.

Example Request
{
"partsMutation": {
"operationType": "insert_table_rows",
"version": "etrver_4tSNBOhFN0",
"documentPartId": "docpart_2mWG2SPvHX",
"rows": [
{
"cells": [
{ "columnIndex": 0, "inputValue": { "type": "object_link_value", "id": "seq_GY9TBGyE12" } },
{ "columnIndex": 1, "inputValue": { "type": "decimal_value", "value": "412.5" } }
]
},
{
"cells": [
{ "columnIndex": 0, "inputValue": { "type": "object_link_value", "id": "seq_EgpEP0tiai" } },
{
"columnIndex": 1,
"inputValue": { "type": "decimal_value", "value": "88.0" },
"format": { "backgroundColor": "#F8B4B4" }
}
]
}
]
}
}

Two optional properties control where the rows go:

  • position sets where the rows are inserted. The only supported value is end_of_table, which is the default.
  • replaceEmptyTrailingRows, when true, replaces any empty rows at the end of the table with the new rows, instead of inserting after them. A row is empty when it’s unsubmitted and every cell matches its column’s default value. This helps with templates that start with blank rows. Defaults to false.

To find a column’s columnIndex, look the column up by name in the table’s columnDefinitions. Matching by name keeps an integration working if the columns are reordered.

Updating cells

Each cell update targets one cell by rowIndex and columnIndex, both counted from 0. In each update:

  • inputValue: include it to change the value, set it to null to clear the value, or leave it out to keep the existing value.
  • format: include it to change the cell’s formatting.

This example changes one value, and highlights another cell without changing its value.

Example Request
{
"partsMutation": {
"operationType": "update_table_cells",
"version": "etrver_9KdQ2mVbXe",
"documentPartId": "docpart_2mWG2SPvHX",
"cellUpdates": [
{
"rowIndex": 3,
"columnIndex": 1,
"inputValue": { "type": "decimal_value", "value": "405.0" }
},
{
"rowIndex": 3,
"columnIndex": 0,
"format": { "backgroundColor": "#FDC68A" }
}
]
}
}

Cell value types

Unstructured table cells always take a text_value. Structured table cells take the type that matches the column’s cellValueType, or a text_value holding a formula.

TypeShapeNotes
text_value{ "type": "text_value", "value": "..." }
integer_value{ "type": "integer_value", "value": 882 }
decimal_value{ "type": "decimal_value", "value": "99.5" }value is a string, to preserve precision.
boolean_value{ "type": "boolean_value", "value": true }
date_value{ "type": "date_value", "value": "2026-10-05" }
datetime_value{ "type": "datetime_value", "value": "2026-10-05T22:34:00Z" }Expects UTC.
object_link_value{ "type": "object_link_value", "id": "seq_GY9TBGyE12" }Links to one Benchling item, such as an entity.
object_link_list_value{ "type": "object_link_list_value", "ids": ["...", "..."] }Links to several Benchling items.