Column values
How to find a column's ID, and the value each column type holds when you read and write items.
An item has a name and a set of values, one for each column that holds something. It also has a groupId and a position: the group of the board it is in, and its place there. Those are fields of the item, not columns, so they are never in values.
Column IDs
Every column on a board has an ID. You use it to read and write that column's value.
- Where to find them. Read the board with
GET /v1/boards/{boardId}. Itscolumnslist every live column, Name first, then the others in order. Each column has itsid,name,typeandsettings. - Name is special. The Name column's ID is always
name, and its type isname. Its value is the item's ownnamefield, not a key ofvalues. It is always first, and you can't delete it, copy it or change its type. - Choose an ID, or let the API make one. When you create a column, you can give it an
id, such asopen_price. Leave it out and the API makes one from the type and a few random characters, such asstatus_k3x9p2ma. - IDs never change. Renaming a column keeps its ID, so code that writes to
open_pricekeeps working after a rename. - The shape. Up to 40 lowercase letters, digits and underscores, starting with a letter.
nameis reserved for the Name column. - Unique on the board. A deleted column's ID counts too. Reusing one answers 409
COLUMN_ID_TAKEN.
[
{
"id": "name",
"name": "Name",
"type": "name",
"description": null,
"settings": {},
"position": 0
},
{
"id": "reference",
"name": "Order number",
"type": "text",
"description": null,
"settings": {},
"position": 1
},
{
"id": "stage",
"name": "Stage",
"type": "status",
"description": null,
"settings": {
"labels": [
{ "id": "k3x9p2ma", "name": "Booked", "color": "blue" },
{ "id": "m7q2w8ze", "name": "In progress", "color": "amber" },
{ "id": "p4n6r1tb", "name": "Done", "color": "teal" }
]
},
"position": 2
}
]Reading values
Every answer that holds an item gives the item's values: an object keyed by column ID. Here is an item, read with GET /v1/items/{itemId}:
{
"item": {
"id": "itm_7k2m9q4x8b1n5v3c6z0wd",
"boardId": "brd_4n8q2w6e1r5t9y3u7i0op",
"groupId": "grp_4n8q2w6e1r5t9y3u7i0op",
"position": 1024,
"name": "Acme move",
"values": {
"reference": "ORD-1042",
"stage": "k3x9p2ma",
"quote": 1840.5,
"services": ["h2v8c5xd", "w5b1y7ka"],
"owner": ["Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns"],
"move_date": "2026-12-03",
"contract": {
"url": "https://example.com/contracts/1042",
"text": "Signed contract"
}
},
"createdAt": "2026-11-17T09:12:44.501Z",
"createdBy": "Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns",
"updatedAt": "2026-11-18T15:40:02.117Z",
"updatedBy": "apk_3f8h2j6l9p1r4t7w0y5ab",
"archivedAt": null,
"createdByType": "member",
"updatedByType": "api_key"
},
"formerMembers": [],
"apiKeys": [
{ "id": "apk_3f8h2j6l9p1r4t7w0y5ab", "name": "Quote sync", "revoked": false }
]
}- Empty cells are left out. An empty cell has no key in
values. The schema also allowsnull, so treat a missing key andnullthe same way: both mean empty. - Only live columns appear. The values of a deleted column are kept but not shown. If the column is restored, they come back.
- Button columns never appear, because a button holds no value.
- The shape of a value depends on its column's type. Each type has its own section below.
Writing values
You write values when you create an item, with POST /v1/boards/{boardId}/items, and when you update one, with PATCH /v1/items/{itemId}. Both take values, keyed by column ID, next to the item's name. A create also takes groupId, the group to put the item in (left out, the board's first group), and position, top or end of that group (left out, end). A PATCH can't change the item's group or place, and answers 400 INVALID_REQUEST if it sends groupId or position. To move an item, use POST /v1/items/{itemId}/move.
This PATCH body sets two columns and empties two others:
{
"values": {
"stage": "In progress",
"quote": 1950,
"services": [],
"move_date": null
}
}- A value sets the whole value of its column. For a dropdown or person column, send the full list, not only what you add.
- A column you leave out stays as it is. On a create, it starts empty.
nullempties a column. For every type except Button,""and[]also mean empty.- Labels and options can be given by ID or by exact name. The API stores the ID either way. See Status and Dropdown.
- A batch takes the same values. Each entry of a batch takes
valuesas one create or update does.
When a value doesn't fit
A value that does not fit its column answers 400 VALUE_INVALID, and nothing is written. The details name the column, the reason and a short message:
{
"error": {
"code": "VALUE_INVALID",
"details": {
"columnId": "stage",
"reason": "unknown_label",
"message": "The column has no such label."
}
}
}reason | When |
|---|---|
invalid | The value has the wrong type or form for its column. Also a key that is not a live column of the board, and any value but null for a Button column |
unknown_label | A status value names no label of the column |
unknown_option | A dropdown value names no option of the column |
unknown_person | A person who is not a current member of the workspace, and not already in that cell of that item |
too_large | The item's values would be over the size limit |
- Only the first problem found is reported. Fix it and send again.
- A key shaped like a column ID that is not a live column of the board, such as
zzzor a deleted column's ID, answersVALUE_INVALIDwith the reasoninvalid. - In a create or a
PATCH, a key that is not shaped like a column ID, such asNameortoString, answers 400INVALID_REQUESTinstead. So doesname: set the item's name with thenamefield. - In a batch, each problem comes back as one entry of
BATCH_INVALID, with the entry'sindex, the codeVALUE_INVALIDand thecolumnId.
Errors lists every code.
Types at a glance
| Type | type | You write | You read back |
|---|---|---|---|
| Text | text | A string | The same |
| Long text | long_text | A string | The same |
| Number | number | A JSON number | The same |
| Status | status | A label's ID or exact name | The label's ID |
| Dropdown | dropdown | A list of option IDs or exact names | A list of option IDs |
| Person | person | A list of user IDs | The same |
| Date | date | YYYY-MM-DD, or a UTC time when the column includes a time | The same |
| Link | link | An object with url and an optional text | The same |
| Phone | phone | A string in E.164 form | The same |
email | A string | The same | |
| Button | button | No value | Never in values |
| Name | name | The item's name field: up to 300 characters, trimmed, not empty | The item's name |
Text
One line of text.
- Value: a string of up to 1,000 characters. You read back the same string.
{ "values": { "reference": "ORD-1042" } }ColumnValueTextstringrequired
A text column's value: 1 to 1,000 characters.
- 1 to 1,000 characters
Long text
Several lines of plain text. Put a new line in the string as \n. The app shows it as plain text; for formatted writing, use the item's notes, which are Markdown.
- Value: a string of up to 10,000 characters. You read back the same string.
{
"values": {
"access_notes": "Elevator booked 9 to 11am.\nLoading dock on Pine St."
}
}ColumnValueLongTextstringrequired
A long text column's value: 1 to 10,000 characters.
- 1 to 10,000 characters
Number
A decimal number.
- Value: a JSON number from -1,000,000,000,000,000 to 1,000,000,000,000,000. A number in quotes, such as
"1840", is refused. - Stored as sent. The API keeps the number you send and does not round it. The column's settings only change how the app shows it:
decimals(up to 10 places), and aprefixandsuffixof up to 10 characters each, such as$ormi.
{ "values": { "quote": 1840.5 } }ColumnValueNumbernumberrequired
A number column's value: a number from -1,000,000,000,000,000 to 1,000,000,000,000,000.
- -1,000,000,000,000,000 to 1,000,000,000,000,000
Status
One label from the column's list, or none.
- The labels are in the column's
settings.labels, each with anid, anameand acolor. Names are unique in a column. - Write the label's ID or its exact name, with the same capitals. The API looks for an ID first, then a name. A name the column doesn't have answers
VALUE_INVALIDwith the reasonunknown_label. It never creates a label. - Read back the label's ID, always. Renaming a label keeps its ID, so the items' values don't change.
- Limits: up to 40 labels in a column, each name up to 40 characters.
- Label IDs. When you create or change the column, you can give each label an
id, or leave it out and the API makes one. A label ID uses the same characters as a column ID, and it may start with a digit. - Removing a label from the column's settings empties the cells that hold it. Send the column's
PATCHwithdryRun: truefirst to see how many items it would empty.
{ "values": { "stage": "Booked" } }In the item's values, you read back the ID:
{ "stage": "k3x9p2ma" }ColumnValueStatusstringrequired
A status column's value: a label's ID. A write may give the label's exact name instead, 1 to 40 characters.
- 1 to 40 characters
Dropdown
One or several options from the column's list.
- The options are in the column's
settings.options, each with anid, anameand acolor.settings.multiplesays whether a cell can hold several. Names are unique in a column. - Write a list of option IDs or exact names, with the same capitals. It is always a list, also when the column allows one option. Each option may appear once. A name the column doesn't have answers
VALUE_INVALIDwith the reasonunknown_option. It never creates an option. - Read back a list of option IDs, in the order you sent them.
- Limits: one option in a cell when the column allows one, and up to 25 when it allows several. Up to 100 options in a column, each name up to 40 characters.
- Option IDs work as label IDs do: you can give them when you create or change the column, or the API makes them.
- Removing an option from the column's settings takes it out of every cell that holds it. A cell keeps its other options. Send the column's
PATCHwithdryRun: truefirst to see how many items it would change.
Mix names and IDs as you like. Here services allows several options and home_size allows one:
{
"values": {
"services": ["Packing", "w5b1y7ka"],
"home_size": ["2 bedrooms"]
}
}In the item's values, you read back the IDs:
{
"services": ["h2v8c5xd", "w5b1y7ka"],
"home_size": ["t6g1u9pc"]
}ColumnValueDropdownarray of stringrequired
A dropdown column's value: a list of 1 to 25 option IDs, each once. A write may give an option's exact name instead of its ID. When the column's
multipleis false, the list holds one option.- 1 to 25 items
Person
Members of your workspace.
- Write a list of user IDs. It is always a list, also when the column allows one person. Each person may appear once. You read back the same list, in the order you sent it.
- Find user IDs with
GET /v1/workspace/members. Use each member'suserId, not itsid. - Current members only. Each person must be a current member of the workspace, or already be in that cell of that item. Someone who left the workspace stays on the items they were on, so a write that sends them back in the same cell works. They can't be added anywhere new: that answers
VALUE_INVALIDwith the reasonunknown_person. - Former members. Every answer that holds items lists, in
formerMembers, the people those items name who are no longer members, with their names. - Limits: one person in a cell when the column allows one (
settings.multipleisfalse, the default), and up to 20 when it allows several.
{
"members": [
{
"id": "Zx4Cv7Bn2Mq9Wl5Ek8Rj1Th6Yg3Ud0Fs",
"userId": "Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns",
"name": "Dana Reyes",
"email": "dana@example.com",
"role": "owner",
"isYou": false
},
{
"id": "Mn3Bv8Cx1Za6Sd2Fg7Hj4Kl9Qw5Er0Ty",
"userId": "Pw3Rk8Ty1Ui6Op2As7Df4Gh9Jk5Lz0Xc",
"name": "Sam Ortiz",
"email": "sam@example.com",
"role": "member",
"isYou": false
}
],
"seats": { "used": 2, "limit": null }
}Here owner allows one person and crew allows several:
{
"values": {
"owner": ["Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns"],
"crew": ["Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns", "Pw3Rk8Ty1Ui6Op2As7Df4Gh9Jk5Lz0Xc"]
}
}ColumnValuePersonarray of stringrequired
A person column's value: a list of 1 to 20 user IDs, each once, each a current member or already in that cell. When the column's
multipleis false, the list holds one person.- 1 to 20 items
Date
A date, or a date with a time.
settings.includeTimesays which. It is chosen when the column is created and can't change: a change answers 400INVALID_REQUESTwith the reasoninclude_time_locked.- Without a time, the value is a calendar date written
YYYY-MM-DD, such as2026-12-03. No time zone moves it. - With a time, the value is a moment in UTC, written exactly
YYYY-MM-DDTHH:MM:SS.sssZ, such as2026-12-03T14:30:00.000Z. Turn local times into UTC before you send them. The app shows the time in each viewer's own time zone. In JavaScript,toISOString()writes this form. - Exactly that form. Other forms are refused, such as a time without milliseconds or with an offset like
+01:00. So are dates that don't exist, such as2026-02-30, a time in a column without one, and a date alone in a column with a time. Because the form is fixed, sorting the text sorts by time. - Read back the same text.
Here move_date has no time and arrives_at has one:
{
"values": {
"move_date": "2026-12-03",
"arrives_at": "2026-12-03T14:30:00.000Z"
}
}ColumnValueDatestringrequired
A date column's value: a real calendar date written
YYYY-MM-DD.- Format
date(ISO 8601)
- Format
ColumnValueDateTimestringrequired
The value of a date column that includes a time: a moment in UTC written
YYYY-MM-DDTHH:MM:SS.sssZ.- Format
date-time(ISO 8601)
- Format
Link
A web address, with optional text to show instead of it.
- Value: an object with
urland, if you like,text. It takes no other keys. You read back the same object. urlis a fullhttporhttpsaddress, with its scheme, of up to 2,000 characters.textis up to 200 characters, and not empty.
{
"values": {
"contract": {
"url": "https://example.com/contracts/1042",
"text": "Signed contract"
}
}
}urlstringrequired
The address:
httporhttps, up to 2,000 characters.- Up to 2,000 characters
- Format
uri
textstringoptional
Text to show in place of the address, 1 to 200 characters.
- 1 to 200 characters
Phone
A phone number in international E.164 form.
- Value: a string with
+and then 7 to 15 digits: the country code, then the number, such as+15551234567. No spaces, dashes or brackets. You read back the same string. - The API adds no country code. The column's
settings.defaultCountryis only used by the app, when a person types a number without+.
{ "values": { "phone": "+15551234567" } }ColumnValuePhonestringrequired
A phone column's value: a number in international (E.164) form,
+and 7 to 15 digits, such as+15551234567.- Pattern
^\+[1-9]\d{6,14}$
- Pattern
An email address.
- Value: a string that looks like
name@example.com, of up to 254 characters. You read back the same string.
{ "values": { "email": "dana@example.com" } }ColumnValueEmailstringrequired
An email column's value: an email address, up to 254 characters.
- Up to 254 characters
- Format
email
Button
A button in the app that opens a web address built from the item's fields. It holds no value.
- Never in
values. A button column has no key in an item'svalues. - Writing: a write may send
nullfor a button column, which changes nothing. Any other value answersVALUE_INVALIDwith the reasoninvalid, and so do""and[]. - Settings: a
labelof up to 40 characters and aurlTemplateof up to 2,000. The app uses them to draw the button. - A button column can't be sorted, filtered or used in a Group by. See Querying items.
Item size
All the values of one item, written as JSON, can take up to 256 KB (262,144 bytes in UTF-8). Empty cells and the item's name don't count.
- A write that would take an item over the limit answers 400
VALUE_INVALIDwith the reasontoo_large.columnIdnames the largest value the write sent. Nothing is written. - A request body has its own size limit. See Requests.
Changing a column's type
You change a column's type with POST /v1/boards/{boardId}/columns/{columnId}/change-type.
- Try it first. Send
dryRun: true, and the answer says how many values the column holds (valueCount) and how many can't be converted (unconvertibleCount). Nothing changes. - A real change converts what it can and empties the rest. The old value of every item whose cell changed stays in that item's changes, which you read with
GET /v1/items/{itemId}/changes. - Limits. One change converts up to 10,000 values and 8 MB of their JSON. A column that holds more answers 409
LIMIT_REACHED, withdetails.limitset toconversion-valuesorconversion-bytesanddetails.maxto the cap. Nothing changes, and the dry run is refused too. A change to Button, and a change that keeps every value as it is (text to long text, and email or phone to text or long text), has no such limit.
What converts:
| From | To | How |
|---|---|---|
| Text, long text | Number | When the text reads as a number, with no thousands separators |
| Number | Text, long text | The number, written plainly |
| Text, long text, email | Each other | When the text still fits the new column |
| Status | Dropdown | By label name |
| Dropdown | Status | By option name. A cell with several options takes its first option that matches a label |
| Text, long text | Status, dropdown | By label name: an exact match first, then ignoring capitals. For a dropdown that allows several, a comma-separated list of names |
| Text, long text | Date | A date or a UTC time written as above. A date in a column with a time becomes midnight UTC; a time in a column without one keeps only its date |
| Text, long text | Phone | When the text is an E.164 number once spaces, dots, dashes and brackets are taken out |
| Text, long text | Link | When the text is a full http or https address. It becomes the url |
| Status, dropdown, date, link, phone | Text, long text | The label or option names joined by ", ", the date's text, the link's url, or the phone number |
| Anything else | Emptied. Every change to Button empties the column, and nothing converts to or from Person |
- Labels made for you. A change from text or long text to status or dropdown that gives no
settingsmakes one label for each distinct value, the most used first, up to 40 labels for a status and 100 options for a dropdown. A value that gets no label is emptied. A change between status and dropdown with nosettingskeeps the labels, with their IDs and colors. - Every converted value fits the new column, as if you had written it.