Skip to content
MelonforceAPI docs

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}. Its columns list every live column, Name first, then the others in order. Each column has its id, name, type and settings.
  • Name is special. The Name column's ID is always name, and its type is name. Its value is the item's own name field, not a key of values. 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 as open_price. Leave it out and the API makes one from the type and a few random characters, such as status_k3x9p2ma.
  • IDs never change. Renaming a column keeps its ID, so code that writes to open_price keeps working after a rename.
  • The shape. Up to 40 lowercase letters, digits and underscores, starting with a letter. name is reserved for the Name column.
  • Unique on the board. A deleted column's ID counts too. Reusing one answers 409 COLUMN_ID_TAKEN.
A board's columns, cut short
[
  {
    "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}:

An item
{
  "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 allows null, so treat a missing key and null the 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:

Set and empty values
{
  "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.
  • null empties 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 values as 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:

A value that doesn't fit
{
  "error": {
    "code": "VALUE_INVALID",
    "details": {
      "columnId": "stage",
      "reason": "unknown_label",
      "message": "The column has no such label."
    }
  }
}
reasonWhen
invalidThe 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_labelA status value names no label of the column
unknown_optionA dropdown value names no option of the column
unknown_personA person who is not a current member of the workspace, and not already in that cell of that item
too_largeThe 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 zzz or a deleted column's ID, answers VALUE_INVALID with the reason invalid.
  • In a create or a PATCH, a key that is not shaped like a column ID, such as Name or toString, answers 400 INVALID_REQUEST instead. So does name: set the item's name with the name field.
  • In a batch, each problem comes back as one entry of BATCH_INVALID, with the entry's index, the code VALUE_INVALID and the columnId.

Errors lists every code.

Types at a glance

TypetypeYou writeYou read back
TexttextA stringThe same
Long textlong_textA stringThe same
NumbernumberA JSON numberThe same
StatusstatusA label's ID or exact nameThe label's ID
DropdowndropdownA list of option IDs or exact namesA list of option IDs
PersonpersonA list of user IDsThe same
DatedateYYYY-MM-DD, or a UTC time when the column includes a timeThe same
LinklinkAn object with url and an optional textThe same
PhonephoneA string in E.164 formThe same
EmailemailA stringThe same
ButtonbuttonNo valueNever in values
NamenameThe item's name field: up to 300 characters, trimmed, not emptyThe item's name

Text

One line of text.

  • Value: a string of up to 1,000 characters. You read back the same string.
Write a text value
{ "values": { "reference": "ORD-1042" } }
ColumnValueText

stringrequired

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.
Write a long text value
{
  "values": {
    "access_notes": "Elevator booked 9 to 11am.\nLoading dock on Pine St."
  }
}
ColumnValueLongText

stringrequired

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 a prefix and suffix of up to 10 characters each, such as $ or mi.
Write a number
{ "values": { "quote": 1840.5 } }
ColumnValueNumber

numberrequired

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 an id, a name and a color. 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_INVALID with the reason unknown_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 PATCH with dryRun: true first to see how many items it would empty.
Write a status by name
{ "values": { "stage": "Booked" } }

In the item's values, you read back the ID:

Read back
{ "stage": "k3x9p2ma" }
ColumnValueStatus

stringrequired

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

One or several options from the column's list.

  • The options are in the column's settings.options, each with an id, a name and a color. settings.multiple says 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_INVALID with the reason unknown_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 PATCH with dryRun: true first 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:

Write dropdown values
{
  "values": {
    "services": ["Packing", "w5b1y7ka"],
    "home_size": ["2 bedrooms"]
  }
}

In the item's values, you read back the IDs:

Read back
{
  "services": ["h2v8c5xd", "w5b1y7ka"],
  "home_size": ["t6g1u9pc"]
}
ColumnValueDropdown

array 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 multiple is 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's userId, not its id.
  • 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_INVALID with the reason unknown_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.multiple is false, the default), and up to 20 when it allows several.
The members list
{
  "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:

Write people
{
  "values": {
    "owner": ["Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns"],
    "crew": ["Hq7Lm2Xp9Rt4Vw6Yz1Bc3Df5Gh8Jk0Ns", "Pw3Rk8Ty1Ui6Op2As7Df4Gh9Jk5Lz0Xc"]
  }
}
ColumnValuePerson

array 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 multiple is false, the list holds one person.

  • 1 to 20 items

Date

A date, or a date with a time.

  • settings.includeTime says which. It is chosen when the column is created and can't change: a change answers 400 INVALID_REQUEST with the reason include_time_locked.
  • Without a time, the value is a calendar date written YYYY-MM-DD, such as 2026-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 as 2026-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 as 2026-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:

Write dates
{
  "values": {
    "move_date": "2026-12-03",
    "arrives_at": "2026-12-03T14:30:00.000Z"
  }
}
ColumnValueDate

stringrequired

A date column's value: a real calendar date written YYYY-MM-DD.

  • Format date (ISO 8601)
ColumnValueDateTime

stringrequired

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)

A web address, with optional text to show instead of it.

  • Value: an object with url and, if you like, text. It takes no other keys. You read back the same object.
  • url is a full http or https address, with its scheme, of up to 2,000 characters.
  • text is up to 200 characters, and not empty.
Write a link
{
  "values": {
    "contract": {
      "url": "https://example.com/contracts/1042",
      "text": "Signed contract"
    }
  }
}
url

stringrequired

The address: http or https, up to 2,000 characters.

  • Up to 2,000 characters
  • Format uri
text

stringoptional

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.defaultCountry is only used by the app, when a person types a number without +.
Write a phone number
{ "values": { "phone": "+15551234567" } }
ColumnValuePhone

stringrequired

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}$

Email

An email address.

  • Value: a string that looks like name@example.com, of up to 254 characters. You read back the same string.
Write an email address
{ "values": { "email": "dana@example.com" } }
ColumnValueEmail

stringrequired

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's values.
  • Writing: a write may send null for a button column, which changes nothing. Any other value answers VALUE_INVALID with the reason invalid, and so do "" and [].
  • Settings: a label of up to 40 characters and a urlTemplate of 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_INVALID with the reason too_large. columnId names 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, with details.limit set to conversion-values or conversion-bytes and details.max to 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:

FromToHow
Text, long textNumberWhen the text reads as a number, with no thousands separators
NumberText, long textThe number, written plainly
Text, long text, emailEach otherWhen the text still fits the new column
StatusDropdownBy label name
DropdownStatusBy option name. A cell with several options takes its first option that matches a label
Text, long textStatus, dropdownBy label name: an exact match first, then ignoring capitals. For a dropdown that allows several, a comma-separated list of names
Text, long textDateA 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 textPhoneWhen the text is an E.164 number once spaces, dots, dashes and brackets are taken out
Text, long textLinkWhen the text is a full http or https address. It becomes the url
Status, dropdown, date, link, phoneText, long textThe label or option names joined by ", ", the date's text, the link's url, or the phone number
Anything elseEmptied. 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 settings makes 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 no settings keeps the labels, with their IDs and colors.
  • Every converted value fits the new column, as if you had written it.