Skip to content
MelonforceAPI docs

Columns

A board's columns: their types, settings and order.

Create a column

POST/v1/boards/{boardId}/columns

Adds a column with the ID you choose, or one made from its type. It goes right after afterColumnId (name puts it first), or last. A board holds at most 60 columns besides Name; past that it answers 409 LIMIT_REACHED. A column whose type's indexed role is empty takes the role.

Who can call: Any API key.

Path parameters

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$

Body

A new column. type decides which settings it takes.

One of:

type: "text"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "text"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "long_text"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "long_text"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "number"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "number"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsNumberInputoptional

The column's settings. Left out, the type's defaults apply.

Show 3 fieldsHide 3 fields
decimals

integeroptional

Digits shown after the point, 0 to 10. Defaults to 0.

  • 0 to 10
  • Default 0
prefix

stringoptional

Text shown before the number, such as $, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
suffix

stringoptional

Text shown after the number, such as kg, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "status"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "status"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsStatusInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
labels

array of LabelInputrequired

Every label, in order, up to 40. IDs and names are unique. A label the column has that is left out is removed, and the cells that hold it are emptied.

  • Up to 40 items
Show 3 fieldsHide 3 fields
id

stringoptional

The ID of a label the column has, to keep it. Left out, it is a new label and the API makes its ID.

  • Pattern ^[a-z0-9][a-z0-9_]{0,39}$
name

stringrequired

The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.

  • 1 to 40 characters
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "dropdown"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "dropdown"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDropdownInputoptional

The column's settings. Left out, the type's defaults apply.

Show 2 fieldsHide 2 fields
options

array of LabelInputrequired

Every option, in order, up to 100. IDs and names are unique. An option the column has that is left out is removed from every cell that holds it.

  • Up to 100 items
Show 3 fieldsHide 3 fields
id

stringoptional

The ID of a label the column has, to keep it. Left out, it is a new label and the API makes its ID.

  • Pattern ^[a-z0-9][a-z0-9_]{0,39}$
name

stringrequired

The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.

  • 1 to 40 characters
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
multiple

booleanoptional

Whether a cell may hold more than one option, up to 25. Defaults to false.

  • Default false
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "person"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "person"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPersonInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
multiple

booleanoptional

Whether a cell may hold more than one person, up to 20. Defaults to false.

  • Default false
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "date"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "date"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDateInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
includeTime

booleanoptional

Whether values hold a time as well as a date. Chosen when the column is created; it cannot change. Defaults to false.

  • Default false
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "link"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "link"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "phone"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "phone"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPhoneInputoptional

The column's settings. Left out, the type's defaults apply.

Show 1 fieldHide 1 field
defaultCountry

string or nulloptional

The country the web app assumes for a number typed without +, as a two-letter ISO 3166 code such as US, or null for none. The API always takes E.164. Defaults to null.

  • Default null
  • Pattern ^[A-Z]{2}$
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "email"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "email"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyoptional

The column's settings. Left out, the type's defaults apply.

afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
type: "button"

object

Show 6 fieldsHide 6 fields
id

stringoptional

The column's ID: 1 to 40 lowercase letters, digits and underscores, starting with a letter, unique on the board. Left out, the API makes one from the type, such as status_k3x9p2ma.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "button"
description

string or nulloptional

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsButtonrequired

The column's settings. Required for this type.

Show 2 fieldsHide 2 fields
label

stringrequired

The button's text, 1 to 40 characters, trimmed.

  • 1 to 40 characters
urlTemplate

stringrequired

The address the button opens, 1 to 2,000 characters, trimmed. It may name the item's fields.

  • 1 to 2,000 characters
afterColumnId

stringoptional

Put the column right after this one; name puts it first. Left out, it goes last. Ignored when creating a board.

  • Pattern ^[a-z][a-z0-9_]{0,39}$

Answer201 Created

column

Columnrequired

The column.

Show 12 optionsHide 12 options

One of:

type: "name"

object

Show 6 fieldsHide 6 fields
id

stringrequired

Always name.

  • Always "name"
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

Always name: the item's name. It is the item's name field, not a key of values.

  • Always "name"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

Always {}.

position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "text"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "text"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "long_text"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "long_text"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "number"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "number"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsNumberrequired

The column's settings: their shape depends on the type.

Show 3 fieldsHide 3 fields
decimals

integerrequired

Digits shown after the point, 0 to 10. Defaults to 0.

  • 0 to 10
  • Default 0
prefix

stringrequired

Text shown before the number, such as $, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
suffix

stringrequired

Text shown after the number, such as kg, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "status"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "status"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsStatusrequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
labels

array of Labelrequired

The labels, in order, up to 40. IDs and names are unique in the column.

  • Up to 40 items
Show 3 fieldsHide 3 fields
id

stringrequired

The label's ID. It stays when the label is renamed.

  • Pattern ^[a-z0-9][a-z0-9_]{0,39}$
name

stringrequired

The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.

  • 1 to 40 characters
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "dropdown"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "dropdown"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDropdownrequired

The column's settings: their shape depends on the type.

Show 2 fieldsHide 2 fields
options

array of Labelrequired

The options, in order, up to 100. IDs and names are unique in the column.

  • Up to 100 items
Show 3 fieldsHide 3 fields
id

stringrequired

The label's ID. It stays when the label is renamed.

  • Pattern ^[a-z0-9][a-z0-9_]{0,39}$
name

stringrequired

The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.

  • 1 to 40 characters
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
multiple

booleanrequired

Whether a cell may hold more than one option, up to 25.

  • Default false
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "person"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "person"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPersonrequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
multiple

booleanrequired

Whether a cell may hold more than one person, up to 20. Defaults to false.

  • Default false
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "date"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "date"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsDaterequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
includeTime

booleanrequired

Whether values hold a time as well as a date. Chosen when the column is created; it cannot change. Defaults to false.

  • Default false
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "link"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "link"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "phone"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "phone"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsPhonerequired

The column's settings: their shape depends on the type.

Show 1 fieldHide 1 field
defaultCountry

string or nullrequired

The country the web app assumes for a number typed without +, as a two-letter ISO 3166 code such as US, or null for none. The API always takes E.164. Defaults to null.

  • Default null
  • Pattern ^[A-Z]{2}$
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "email"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "email"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsEmptyrequired

The column's settings: their shape depends on the type.

position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0
type: "button"

object

Show 6 fieldsHide 6 fields
id

stringrequired

The column's ID. It never changes, even when the column is renamed.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
name

stringrequired

The column's name, 1 to 50 characters, trimmed.

  • 1 to 50 characters
type

stringrequired

The column's type.

  • Always "button"
description

string or nullrequired

The column's description, up to 500 characters, or null.

  • Up to 500 characters
settings

ColumnSettingsButtonrequired

The column's settings: their shape depends on the type.

Show 2 fieldsHide 2 fields
label

stringrequired

The button's text, 1 to 40 characters, trimmed.

  • 1 to 40 characters
urlTemplate

stringrequired

The address the button opens, 1 to 2,000 characters, trimmed. It may name the item's fields.

  • 1 to 2,000 characters
position

integerrequired

Its place in the board's order: 0 for Name, which is always first, then 1 and up.

  • At least 0

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carry details.reason, which says why, and details.field, which names the field when one is at fault.

UNAUTHENTICATED

401 Unauthorized

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 Not Found

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

COLUMN_ID_TAKEN

409 Conflict

The column ID is already used on the board, by a deleted column too. Choose another.

LIMIT_REACHED

409 Conflict

A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert. details.limit names it and details.max gives the cap.

PAYLOAD_TOO_LARGE

413 Content Too Large

The body is over its route's size limit. A save of notes with too many characters answers it too, with details.limit notes and details.max.

RATE_LIMITED

429 Too Many Requests

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

Example

Request
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "customer_phone",
  "name": "Customer phone",
  "type": "phone",
  "settings": {
    "defaultCountry": "US"
  },
  "afterColumnId": "name"
}'
201 Created
{
  "column": {
    "id": "customer_phone",
    "name": "Customer phone",
    "type": "phone",
    "description": null,
    "settings": {
      "defaultCountry": "US"
    },
    "position": 1
  }
}

Update a column

PATCH/v1/boards/{boardId}/columns/{columnId}

Changes the name, the description or the settings. settings is the whole of them and is checked against the column's type in a second step; a label or option left out is removed and its cells emptied. Send dryRun: true to count those items without writing anything. The Name column cannot be changed (409 COLUMN_PROTECTED), and when others change the column at the same moment it may answer 503 UNAVAILABLE; send it again.

Who can call: Any API key.

Path parameters

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
columnId

stringrequired

The column's ID.

  • Pattern ^[a-z][a-z0-9_]{0,39}$

Body

The fields to change. Send at least one besides dryRun.

name

stringoptional

The new name, 1 to 50 characters.

  • 1 to 50 characters
description

string or nulloptional

The new description, up to 500 characters; null clears it.

  • Up to 500 characters
settings

one of ColumnSettingsStatusInput, ColumnSettingsDropdownInput, ColumnSettingsButton, ColumnSettingsNumberInput, ColumnSettingsPersonInput, ColumnSettingsDateInput, ColumnSettingsPhoneInput, ColumnSettingsEmptyoptional

The whole of the column's settings, checked against the column's type. A label or option left out is removed, and the cells that hold it are emptied. A date column's includeTime cannot change.

Show 8 optionsHide 8 options

One of:

ColumnSettingsStatusInput

ColumnSettingsStatusInput

The settings of a status column in a request.

Show 1 fieldHide 1 field
labels

array of LabelInputrequired

Every label, in order, up to 40. IDs and names are unique. A label the column has that is left out is removed, and the cells that hold it are emptied.

  • Up to 40 items
Show 3 fieldsHide 3 fields
id

stringoptional

The ID of a label the column has, to keep it. Left out, it is a new label and the API makes its ID.

  • Pattern ^[a-z0-9][a-z0-9_]{0,39}$
name

stringrequired

The label's name, 1 to 40 characters, trimmed. Unique in its column: a write may give a label by its exact name.

  • 1 to 40 characters
color

stringrequired

The label's color.

  • One of "blue", "purple", "amber", "teal", "grey"
ColumnSettingsDropdownInput

ColumnSettingsDropdownInput

The settings of a dropdown column in a request.

Same fields as settings in Create a column

ColumnSettingsButton

ColumnSettingsButton

The settings of a button column. A button has no defaults: it needs both.

Show 2 fieldsHide 2 fields
label

stringrequired

The button's text, 1 to 40 characters, trimmed.

  • 1 to 40 characters
urlTemplate

stringrequired

The address the button opens, 1 to 2,000 characters, trimmed. It may name the item's fields.

  • 1 to 2,000 characters
ColumnSettingsNumberInput

ColumnSettingsNumberInput

The settings of a number column.

Show 3 fieldsHide 3 fields
decimals

integeroptional

Digits shown after the point, 0 to 10. Defaults to 0.

  • 0 to 10
  • Default 0
prefix

stringoptional

Text shown before the number, such as $, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
suffix

stringoptional

Text shown after the number, such as kg, up to 10 characters. Defaults to empty.

  • Up to 10 characters
  • Default ""
ColumnSettingsPersonInput

ColumnSettingsPersonInput

The settings of a person column.

Show 1 fieldHide 1 field
multiple

booleanoptional

Whether a cell may hold more than one person, up to 20. Defaults to false.

  • Default false
ColumnSettingsDateInput

ColumnSettingsDateInput

The settings of a date column.

Show 1 fieldHide 1 field
includeTime

booleanoptional

Whether values hold a time as well as a date. Chosen when the column is created; it cannot change. Defaults to false.

  • Default false
ColumnSettingsPhoneInput

ColumnSettingsPhoneInput

The settings of a phone column.

Show 1 fieldHide 1 field
defaultCountry

string or nulloptional

The country the web app assumes for a number typed without +, as a two-letter ISO 3166 code such as US, or null for none. The API always takes E.164. Defaults to null.

  • Default null
  • Pattern ^[A-Z]{2}$
ColumnSettingsEmpty

ColumnSettingsEmpty

Text, long text, link and email columns, and the Name column, have no settings: {}.

dryRun

booleanoptional

With true, nothing is written: the answer only counts the items that would lose a label or option.

Answer200 OK

column

Columnrequired

The column after the change; on a dry run, the column as it is.

Same options as column in Create a column

dryRun

booleanrequired

Whether this was a dry run.

clearedCount

integerrequired

The items whose cell held a label or option the request removed: emptied, or on a dry run, that would be.

  • At least 0

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carry details.reason, which says why, and details.field, which names the field when one is at fault.

UNAUTHENTICATED

401 Unauthorized

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 Not Found

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

COLUMN_PROTECTED

409 Conflict

The Name column cannot be changed with a PATCH, deleted, copied or change type, and cannot be named as one of the board's indexed columns.

PAYLOAD_TOO_LARGE

413 Content Too Large

The body is over its route's size limit. A save of notes with too many characters answers it too, with details.limit notes and details.max.

RATE_LIMITED

429 Too Many Requests

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 Service Unavailable

Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the Idempotency-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X PATCH "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/status" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Stage",
  "settings": {
    "labels": [
      {
        "id": "k4m9q2xa",
        "name": "Booked",
        "color": "blue"
      },
      {
        "id": "p7t3w8nc",
        "name": "Packing",
        "color": "amber"
      },
      {
        "id": "d2h6j1rv",
        "name": "Moved",
        "color": "teal"
      },
      {
        "name": "On hold",
        "color": "grey"
      }
    ]
  }
}'
200 OK
{
  "column": {
    "id": "status",
    "name": "Stage",
    "type": "status",
    "description": null,
    "settings": {
      "labels": [
        {
          "id": "k4m9q2xa",
          "name": "Booked",
          "color": "blue"
        },
        {
          "id": "p7t3w8nc",
          "name": "Packing",
          "color": "amber"
        },
        {
          "id": "d2h6j1rv",
          "name": "Moved",
          "color": "teal"
        },
        {
          "id": "h5c8z3qe",
          "name": "On hold",
          "color": "grey"
        }
      ]
    },
    "position": 1
  },
  "dryRun": false,
  "clearedCount": 0
}

Delete a column

DELETE/v1/boards/{boardId}/columns/{columnId}

Moves the column to the trash. Its values stay, and restoring the column brings them back. An indexed role it held passes to the next column that fits, or is emptied when none does. With Claim on, the person role is emptied, not passed on. The Name column cannot be deleted (409 COLUMN_PROTECTED).

Who can call: Any API key.

Path parameters

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
columnId

stringrequired

The column's ID.

  • Pattern ^[a-z][a-z0-9_]{0,39}$

Answer200 OK

An empty object, {}.

Errors

UNAUTHENTICATED

401 Unauthorized

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 Not Found

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

COLUMN_PROTECTED

409 Conflict

The Name column cannot be changed with a PATCH, deleted, copied or change type, and cannot be named as one of the board's indexed columns.

RATE_LIMITED

429 Too Many Requests

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 Service Unavailable

Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the Idempotency-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X DELETE "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/customer_phone" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{}

Restore a column

POST/v1/boards/{boardId}/columns/{columnId}/restore

Brings a deleted column back with its values, at its own place in the board's order: after the columns that were before it when it was deleted. It takes its type's indexed role when that role is empty; with Claim on, it takes the person role only if it held that role when it was deleted. A board already at 60 columns answers 409 LIMIT_REACHED, and a column that is not deleted answers 404.

Who can call: Any API key.

Path parameters

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
columnId

stringrequired

The column's ID.

  • Pattern ^[a-z][a-z0-9_]{0,39}$

Answer200 OK

column

Columnrequired

The column.

Same options as column in Create a column

Errors

UNAUTHENTICATED

401 Unauthorized

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 Not Found

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

LIMIT_REACHED

409 Conflict

A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert. details.limit names it and details.max gives the cap.

RATE_LIMITED

429 Too Many Requests

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

Example

Request
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/customer_phone/restore" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY"
200 OK
{
  "column": {
    "id": "customer_phone",
    "name": "Customer phone",
    "type": "phone",
    "description": null,
    "settings": {
      "defaultCountry": "US"
    },
    "position": 1
  }
}

Duplicate a column

POST/v1/boards/{boardId}/columns/{columnId}/duplicate

Copies a column right after the original, with its values unless withValues is false. Left out, the copy's name is the original's with " copy" added, and its ID is made from the type. The body may be empty. The 60-column limit applies, and the Name column cannot be copied (409 COLUMN_PROTECTED).

Who can call: Any API key.

Path parameters

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
columnId

stringrequired

The column's ID.

  • Pattern ^[a-z][a-z0-9_]{0,39}$

Body

name

stringoptional

The copy's name, 1 to 50 characters. Left out, the original's name and " copy".

  • 1 to 50 characters
id

stringoptional

The copy's ID, unique on the board. Left out, the API makes one from the type.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
withValues

booleanoptional

Whether to copy the values too. Defaults to true.

  • Default true

Answer201 Created

column

Columnrequired

The column.

Same options as column in Create a column

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carry details.reason, which says why, and details.field, which names the field when one is at fault.

UNAUTHENTICATED

401 Unauthorized

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 Not Found

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

COLUMN_ID_TAKEN

409 Conflict

The column ID is already used on the board, by a deleted column too. Choose another.

COLUMN_PROTECTED

409 Conflict

The Name column cannot be changed with a PATCH, deleted, copied or change type, and cannot be named as one of the board's indexed columns.

LIMIT_REACHED

409 Conflict

A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert. details.limit names it and details.max gives the cap.

PAYLOAD_TOO_LARGE

413 Content Too Large

The body is over its route's size limit. A save of notes with too many characters answers it too, with details.limit notes and details.max.

RATE_LIMITED

429 Too Many Requests

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

Example

Request
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/move_date/duplicate" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id": "delivery_date",
  "name": "Delivery date",
  "withValues": false
}'
201 Created
{
  "column": {
    "id": "delivery_date",
    "name": "Delivery date",
    "type": "date",
    "description": null,
    "settings": {
      "includeTime": false
    },
    "position": 3
  }
}

Change a column's type

POST/v1/boards/{boardId}/columns/{columnId}/change-type

Converts the column's values to another type; values that cannot convert are emptied. Send dryRun: true to count them first without writing anything. settings is for the new type and is checked against it in a second step; left out, the type's defaults apply, with labels or options made from the values. When the values are converted one by one, a column of more than 10,000 values or 8 MiB of values answers 409 LIMIT_REACHED. A change to Button, text to long text, and email or phone to text or long text convert no value one by one and have no such limit. The Name column cannot change type (409 COLUMN_PROTECTED).

Who can call: Any API key.

Path parameters

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$
columnId

stringrequired

The column's ID.

  • Pattern ^[a-z][a-z0-9_]{0,39}$

Body

type

stringrequired

The new type.

  • One of "text", "long_text", "number", "status", "dropdown", "person", "date", "link", "phone", "email", "button"
settings

one of ColumnSettingsStatusInput, ColumnSettingsDropdownInput, ColumnSettingsButton, ColumnSettingsNumberInput, ColumnSettingsPersonInput, ColumnSettingsDateInput, ColumnSettingsPhoneInput, ColumnSettingsEmptyoptional

Settings for the new type, checked against it. Left out, the type's defaults apply, with labels or options made from the values where the types allow it. A button needs them.

Same options as settings in Update a column

dryRun

booleanoptional

With true, nothing is written: the answer only counts the values. Defaults to false.

  • Default false

Answer200 OK

dryRun

booleanrequired

Whether this was a dry run.

valueCount

integerrequired

The number of values the column holds.

  • At least 0
unconvertibleCount

integerrequired

How many of them cannot be converted: emptied by a real change (the change log keeps them), or on a dry run, that would be.

  • At least 0
column

Column or nullrequired

The changed column; null on a dry run.

Same options as column in Create a column

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carry details.reason, which says why, and details.field, which names the field when one is at fault.

UNAUTHENTICATED

401 Unauthorized

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 Not Found

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

COLUMN_PROTECTED

409 Conflict

The Name column cannot be changed with a PATCH, deleted, copied or change type, and cannot be named as one of the board's indexed columns.

LIMIT_REACHED

409 Conflict

A limit is full: a board's columns or views, its live groups (at most 50, on a group create or restore), or the values a type change would convert. details.limit names it and details.max gives the cap.

PAYLOAD_TOO_LARGE

413 Content Too Large

The body is over its route's size limit. A save of notes with too many characters answers it too, with details.limit notes and details.max.

RATE_LIMITED

429 Too Many Requests

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 Service Unavailable

Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the Idempotency-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/truck/change-type" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "dropdown"
}'
200 OK
{
  "dryRun": false,
  "valueCount": 12,
  "unconvertibleCount": 0,
  "column": {
    "id": "truck",
    "name": "Truck",
    "type": "dropdown",
    "description": null,
    "settings": {
      "options": [
        {
          "id": "v3n8b1qa",
          "name": "Van",
          "color": "blue"
        },
        {
          "id": "t6r2k9mz",
          "name": "Box truck",
          "color": "purple"
        }
      ],
      "multiple": false
    },
    "position": 4
  }
}

Order columns

POST/v1/boards/{boardId}/columns/order

Send every live column ID except name, once each, in the new order. Anything else answers 400 INVALID_REQUEST with the reason order_mismatch, as does a column created while the request ran. An order the board already has answers 200 and writes nothing.

Who can call: Any API key.

Path parameters

boardId

stringrequired

The board's ID.

  • Pattern ^brd_[0-9a-z]{21}$

Body

columnIds

array of stringrequired

Every live column ID except name, once each, in the new order. Up to 600.

  • Up to 600 items

Answer200 OK

columns

array of Columnrequired

The board's live columns in the new order, Name first.

Same options as column in Create a column

Errors

INVALID_REQUEST

400 Bad Request

The body, a query parameter or the Idempotency-Key does not match its schema, or the request names something the board does not have or allow, such as a column order that is not every column once or the board's last view to delete. An ID in the path that is not shaped like one answers 404 instead. Some refusals carry details.reason, which says why, and details.field, which names the field when one is at fault.

UNAUTHENTICATED

401 Unauthorized

No key was sent, or the key does not work: the header is not Bearer <key>, the key is from another environment, unknown, revoked or expired, or its maker is no longer an owner or admin or its workspace is not active. The answer is the same in every case; when the request had an Authorization header, it comes with WWW-Authenticate: Bearer.

NOT_FOUND

404 Not Found

There is no such board, column, view, group, item or update in the key's workspace (another workspace's counts as none, and so does another board's group in the path), or it was deleted while the request ran. A restore of a board, column or group that is not in the trash answers it too. Nothing is written.

PAYLOAD_TOO_LARGE

413 Content Too Large

The body is over its route's size limit. A save of notes with too many characters answers it too, with details.limit notes and details.max.

RATE_LIMITED

429 Too Many Requests

Too many calls in the last 60 seconds: by the key, by its workspace's keys together, or from your address with keys that do not work. Only keys of the right shape count against your address; a header or key of the wrong shape answers 401 and is not counted. Send it again after Retry-After seconds.

With Retry-After: 10, the seconds to wait before sending again.

INTERNAL

500 Internal Server Error

Something went wrong on our side. Try again later.

UNAVAILABLE

503 Service Unavailable

Others changed the same thing at the same moment and the write ran out of tries or of its statement budget. Or the answer stored for the Idempotency-Key was kept in parts and a part is gone. Nothing was written; send it again after Retry-After seconds.

With Retry-After: 1, the seconds to wait before sending again.

Example

Request
curl -X POST "https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/columns/order" \
  -H "Authorization: Bearer $MELONFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "columnIds": [
    "move_date",
    "status",
    "crew_lead"
  ]
}'
200 OK
{
  "columns": [
    {
      "id": "name",
      "name": "Name",
      "type": "name",
      "description": null,
      "settings": {},
      "position": 0
    },
    {
      "id": "move_date",
      "name": "Move date",
      "type": "date",
      "description": null,
      "settings": {
        "includeTime": false
      },
      "position": 1
    },
    {
      "id": "status",
      "name": "Status",
      "type": "status",
      "description": null,
      "settings": {
        "labels": [
          {
            "id": "k4m9q2xa",
            "name": "Booked",
            "color": "blue"
          },
          {
            "id": "p7t3w8nc",
            "name": "Packing",
            "color": "amber"
          },
          {
            "id": "d2h6j1rv",
            "name": "Moved",
            "color": "teal"
          }
        ]
      },
      "position": 2
    },
    {
      "id": "crew_lead",
      "name": "Crew lead",
      "type": "person",
      "description": "Who runs the crew on the day.",
      "settings": {
        "multiple": false
      },
      "position": 3
    }
  ]
}