Columns
Columns are one of the core elements of any board in monday.com. Boards are formatted as a table with columns and rows. Each column has specific functionality and only stores relevant data. For example, a numbers column will store numerical values, a text column will store text values, and a time tracking column will store only time-based data based on log events.
As a developer working with monday.com, it is important to familiarize yourself with the columns
API so you know how to access and update column data. This document will walk you through the available queries and mutations to read and modify the columns
object via the API.
Queries
Required scope: boards:read
Querying columns
will return metadata about one or a collection of columns. This method accepts various arguments and returns an array.
You can only query columns
by nesting it within another query, so it can't be used at the root. Check out this query in action in our Postman library or follow along with these code samples!
query {
boards (ids: 1234567890) {
columns {
id
title
}
}
}
let query = "query {boards (ids: 1234567890) { columns { id title }}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YourSuperSecretApiKey'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to reduce the number of results returned in your columns
query.
Argument | Description |
---|---|
ids [String] | The specific columns to return. |
types [String] | The specific type of columns to return. |
Fields
You can use the following field(s) to specify what information your columns
query will return.
Field | Field Description |
---|---|
archived Boolean! | Returns true if the column is archived. |
description String | The column's description. |
id ID! | The column's unique identifier. |
pos String (DEPRECATED) | The column's position on the board. This field has been deprecated and will always return null . |
settings_str String! | The column's settings. |
title String! | The column's title. |
type String! | The column's type. |
width Int | The column's width. |
Mutations
Required scope: boards:write
Create a column
The create_column
mutation allows you to create a new column on a board within the account via the API. You can also specify what fields to query back from the new column when you run the mutation.
Check out this mutation in action in our Postman library or follow along with these code samples!
mutation{
create_column(board_id: 1234567890, title:"Work Status", description: "This is my work status column", column_type:status) {
id
title
description
}
}
let query = "mutation { create_column(board_id: 1234567890, title:\"Work Status\", description: \"This is my work status column\", column_type:status){id title description}}"
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define the new column's characteristics.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier where the new column should be created. |
column_type ColumnType | The type of column to create. Check out our list of available column types. |
defaults JSON | The new column's defaults. |
description String | The new column's description. |
id String | The column's user-specified unique identifier. Please note that the mutation will fail if it does not meet any of the following requirements: - [1-20] characters in length (inclusive) - Only lowercase letters (a-z) and underscores (_) - Must be unique (no other column on the board can have the same ID) - Can't reuse column IDs, even if the column has been deleted from the board - Can't be null, blank, or an empty string |
title String! | The new column's title. |
Create a status or dropdown column with custom labels
The create_column
mutation also allows you to create a new status or dropdown column with custom labels via the API. You can also specify what fields to query back from the new column when you run the mutation.
Status column
mutation {
create_column(
board_id: 1234567890
title: "Project domain"
column_type: status
description: "This column indicates the domain of each project."
defaults: "{\"labels\":{\"1\": \"Information technology\", \"2\": \"Human resources\", \"3\": \"Customer service\", \"4\": \"Other\"}}"
) {
id
}
}
let query = "mutation { create_column(board_id: 1234567890, title:\"Project domain\", column_type:status, description: \"This column indicates the domain of each project.\", defaults: \"{\\\"labels\\\":{\\\"1\\\": \\\"Information technology\\\", \\\"2\\\": \\\"Human resources\\\", \\\"3\\\": \\\"Customer service\\\", \\\"4\\\": \\\"Other\\\"}}\"){id}}"
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Dropdown column
mutation {
create_column(
board_id: 1234567890
title: "Keywords"
column_type: dropdown
description: "This column indicates which keywords to include in each project."
defaults: "{\"settings\":{\"labels\":[{\"id\":1,\"name\":\"Technology\"}, {\"id\":2,\"name\":\"Marketing\"}, {\"id\":3,\"name\":\"Sales\"}]}}"
) {
id
}
}
let query = "mutation {create_column(board_id: 1234567890, title: \"Keywords\", column_type: dropdown, description: \"This column indicates which keywords to include in each project.\", defaults: \"{\\\"settings\\\":{\\\"labels\\\":[{\\\"id\\\":1,\\\"name\\\":\\\"Technology\\\"}, {\\\"id\\\":2,\\\"name\\\":\\\"Marketing\\\"}, {\\\"id\\\":3,\\\"name\\\":\\\"Sales\\\"}]}}\") {id}}"
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE’
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define the new column's characteristics.
Argument | Description |
---|---|
board_id Int! | The board's unique identifier where the new column should be created. |
column_type ColumnType | The type of column to create. Check out our list of available column types. |
defaults JSON | The new column's defaults. |
description String | The new column's description. |
id String | The column's user-specified unique identifier. Please note that the mutation will fail if it does not meet any of the following requirements: - [1-20] characters in length (inclusive) - Only lowercase letters (a-z) and underscores (_) - Must be unique (no other column on the board can have the same ID) - Can't reuse column IDs, even if the column has been deleted from the board - Can't be null, blank, or an empty string |
title String! | The new column's title. |
Change a simple column value
The change_simple_column_value
mutation allows you to change the value of a column in a specific item (row) with a string value via the API. Each column has a certain type, and different column types expect a different set of parameters to update their values. You can also specify what fields to query back when you run the mutation.
Pro tip
You can use simple (
string
) values, regular (JSON
) values, as well as a combination of both in yourcreate_item()
,create_subitem()
andchange_multiple_column_values()
mutations. Both value types can be useful when you want to update columns that do not support simple values.
Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
change_simple_column_value (board_id: 1234567890, item_id: 9876543210, column_id: "status", value: "Working on it") {
id
}
}
var query = "mutation {change_simple_column_value (board_id: 1234567890, item_id: 9876543210, column_id: \"status\", value: \"Working on it\") {id}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query': "mutation {change_simple_column_value (board_id: 1234567890, item_id: 9876543210, column_id: \"status\", value: \"Working on it\") {id}}"
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which column to change and its new value.
Argument | Description |
---|---|
board_id Int! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id Int | The unique identifier of the item to change. |
value String! | The new simple value of the column. You can find more about simple column values in our Column Types Reference. |
Change a column value
The change_column_value
mutation allows you to change the value of a column in a specific item (row) with a JSON value via the API. If you’re using JavaScript, you can use JSON.stringify()
to convert a JSON
object into a string. You can also specify what fields to query back when you run the mutation.
Check out this mutation in action in our Postman library or follow along with these code samples!
mutation {
change_column_value (board_id: 1234567890, item_id: 9876543210, column_id: "email9", value: "{\"text\":\"[email protected]\",\"email\":\"[email protected]\"}") {
id
}
}
var query = "mutation { change_column_value (board_id: 1234567890, item_id: 9876543210, column_id: \"email9\", value: \"{\\\"text\\\":\\\"[email protected]\\\",\\\"email\\\":\\\"[email protected]\\\"}\") {id}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which column to change and its new value.
Argument | Description |
---|---|
board_id Int! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id Int | The unique identifier of the item to change. |
value JSON! | The new value of the column in JSON format. You can find more about these JSON values in our Column Types Reference. |
Change multiple column values
The change_multiple_column_values
mutation allows you to change multiple column values of a specific item (row) with a JSON value via the API. You can also specify what fields to query back when you run the mutation.
Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data in the column_values
argument, use a string and build it using this sample form: {\"text\": \"New text\", \"status\": {\"label\": \"Done\"}}
Pro tip
You can also use simple (
String
) values in this mutation along with regular (JSON
) values, or just simple values. Here's an example of setting a status with a simple value:{\"text\": \"New text\", \"status\": \"Done\"}
mutation {
change_multiple_column_values (item_id: 1234567890, board_id: 9876543210, column_values: "{\"status\": {\"index\": 1},\"date4\": {\"date\":\"2021-01-01\"}, \"person\" : {\"personsAndTeams\":[{\"id\":9603417,\"kind\":\"person\"}]}}") {
id
}
}
var query = "mutation {change_multiple_column_values (item_id: 1234567890, board_id: 9876543210, column_values: \"{\\\"status\\\": {\\\"index\\\": 1},\\\"date4\\\": {\\\"date\\\":\\\"2021-01-01\\\"}, \\\"person\\\" : {\\\"personsAndTeams\\\":[{\\\"id\\\":9603417,\\\"kind\\\":\\\"person\\\"}]}}\") {id}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which columns to change and their new values.
Argument | Definition |
---|---|
board_id Int! | The unique identifier of the board that contains the columns to change. |
column_values JSON! | The updated column values. |
create_labels_if_missing Boolean | Creates status/dropdown labels if they are missing. Requires permission to change the board structure. |
item_id Int | The unique identifier of the item to change. |
Change a column title
The change_column_title
mutation allows you to change the title of an existing column via the API. You can also specify what fields to query back when you run the mutation.
mutation {
change_column_title (board_id: 1234567890, column_id: "status", title: "new_status") {
id
}
}
var query = "mutation {change_column_title (board_id: 1234567890, column_id: \"status\", title: \"new_status\") {id}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which column's title to change and its new value.
Argument | Definition |
---|---|
board_id Int! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
title String! | The column's new title. |
Change column metadata
The change_column_metadata
mutation allows you to update the metadata of an existing column. Currently, we support updating both the title and description. You can also specify what fields to query back when you run the mutation.
mutation {
change_column_metadata(board_id: 1234567890, column_id: "date4", column_property: description, value: "This is my awesome date column"){
id
title
description
}
}
var query = "mutation {change_column_metadata (board_id: 1234567890, column_id: \"date4\", column_property: description, value: \"This is my awesome date column\") {id}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which column to change and its new value.
Argument | Definition |
---|---|
board_id Int! | The unique identifier of the board that contains the column to change. |
column_id String! | The column's unique identifier. |
column_property ColumnProperty | The property you want to change: title or description. |
value String | The new value of that property. |
Delete a column
The delete_column
mutation allows you to delete a single column from a board via the API. You can also specify what fields to query back from the deleted column when you run the mutation.
mutation {
delete_column (board_id: 1234567890, column_id: "status") {
id
}
}
let query = 'mutation { delete_column(board_id: 1234567890, column_id: \"status\") { id }}';
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'YOUR_API_KEY_HERE'
},
body: JSON.stringify({
'query' : query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
Arguments
You can use the following argument(s) to define which column to delete.
Argument | Description |
---|---|
board_id Int! | The unique identifier of the board that contains the column to delete. |
column_id String! | The column's unique identifier. |
Join our developer community!
We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎
Updated 10 days ago