Read and write
Read a board and add rows to it with a board key.
Loading documentation…
Read the board
GET /v1/ingest/board · scope read
bash
The answer carries the board's columns, a page of rows (newest first), total, and write —
exactly what a new row takes on this board.
| Query | Meaning |
|---|---|
limit | Rows per page. Default 100, at most 1000. |
cursor | The nextCursor from the previous page. Opaque. nextCursor is null on the last page. |
rows=false | The shape and write only, no rows — the cheap way to learn what a row takes. Needs read. |
What a row takes
data.write.columns lists every column: its id and label (either works as a cell key), its
kind, a format in words, an example, a select's options, a person column's members,
and writable: false with a why for columns the system fills. data.write.example is a whole
body that would land on this board — post it unchanged for a first successful write.
Add a row
POST /v1/ingest/rows · scope rows:write
bash
A 201 answers the row in data and a receipt: filled (columns that now hold a value),
coerced (values changed on the way in — "$1,200.50" stored as 1200.5) and ignored (cells
that stored nothing, and why).
Add many rows
Send rows instead of cells — up to 500, all or nothing. A refusal names every bad row by
its position, so one fix-and-resend is enough:
bash
json
Cell formats
Strings always work; numbers and booleans may be JSON values. Each column's format is the
authority for that board.
| Kind | Send | Example |
|---|---|---|
| text, long_text | text; newlines kept | "Acme Ltd" |
| number, percent | a decimal | 1250.5 |
| currency | an amount; written amounts are read | 25000 or "$25,000" |
| rating | a whole number, 1 to the column's max | 4 |
| date | YYYY-MM-DD | "2026-09-09" |
| datetime | RFC 3339, stored in UTC | "2026-09-09T14:05:00Z" |
| select | one of options | "new" |
| checkbox | a boolean | true |
| url, email, phone | the text | "owner@acme.example" |
| person | a member's id or email, from members | "ana@yourfirm.example" |
| tags | an array of labels, or one | ["referral", "priority"] |
| address | an object; every key optional | {"line1": "1 Main St", "city": "Austin"} |
| relation | {"id", "label"} of a record on the related page | |
| formula, lookup, file | not writable on a new row |
Retrying safely
On a page key (Leads, Deals…), send external_id — your id for the record, up to 255 bytes. Posting
the same one again answers the first record instead of making a second, so a timed-out request can
be retried. Board keys refuse external_id; read the board before re-sending instead.