Columns
Columns and items are two core elements of any board in monday.com. A board is formatted as a table, where there are columns and rows, called items. You can learn more about this object type here.
In monday.com, each column has a specific functionality (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).
Columns Queries
Required scope: boards:read
query {
boards (ids: 1234567) {
owners {
id
}
columns {
title
type
}
}
}
let query = "query {boards (ids: 1234567) {owner{ id } columns { title type }}}";
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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"query { boards (ids: 1234567) {owner{ id } columns { title type }}}"}'
Fields
Querying columns will return either one or a collection of columns.
Columns are available for querying through boards and contain the following fields which will determine the data returned.
Field | Field Description |
---|---|
archived | Whether the column is archived or not. |
id | The column's identifier, unique only to its board. |
pos | The column's position on the board. This field has been deprecated and will always return |
settings_str | The column's settings in a string form. |
title | The column's title. |
description | The column's description. |
type | The column's type. |
width | The column's width. |
Columns Mutations
Required scope: boards:write
Create a Column
This mutation will create a column on a board within the account, using the board ID. After the mutation runs you can query back all the column data as shown in the querying columns section above.
mutation{
create_column(board_id: 12345678, title:"Work Status", description: "This is my work status column", column_type:status) {
id
title
description
}
}
const fetch = require('node-fetch')
let query = "create_column(board_id: 12345678, title:\"Work Status\", description: \"This is my work status column\", column_type:status){id}}"
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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretAPIkey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"create_column(board_id: 12345678, title:\"Work Status\", description: \"This is my work status column\", column_type:status) {id}}"}'
Arguments for Create a Column
The following create_column()
arguments define the new column's characteristics.
Argument | Description |
---|---|
board_id | The board's unique identifier. |
title | The new column's title. |
column_type | The type of column to create (the available column types al listed below). |
defaults | The new column's defaults. |
description | The column's description. |
Available column types:
- auto_number - Number items according to their order in the group/board
- checkbox - Check off items and see what's done at a glance
- country - Choose a country
- color_picker - Manage a design system using a color palette
- creation_log - Add the item's creator and creation date automatically
- date - Add dates like deadlines to ensure you never drop the ball
- dependency - Set up dependencies between items in the board
- dropdown - Create a dropdown list of options
- email - Email team members and clients directly from your board
- file - Add files & docs to your item
- hour - Add times to manage and schedule tasks, shifts and more
- item_id - Show a unique ID for each item
- last_updated - Add the person that last updated the item and the date
- link - Simply hyperlink to any website
- location - Place multiple locations on a geographic map
- long_text - Add large amounts of text without changing column width
- numbers - Add revenue, costs, time estimations and more
- people - Assign people to improve team work
- phone - Call your contacts directly from monday.com
- progress - Show progress by combining status columns in a battery
- rating - Rate or rank anything visually
- status - Get an instant overview of where things stand
- team - Assign a full team to an item
- tags - Add tags to categorize items across multiple boards
- text - Add textual information e.g. addresses, names or keywords
- timeline - Visually see a breakdown of your team's workload by time
- time_tracking - Easily track time spent on each item, group, and board
- vote - Vote on an item e.g. pick a new feature or a favorite lunch place
- week - Select the week on which each item should be completed
- world_clock - Keep track of the time anywhere in the world
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.
Each column has a certain type, and different column types expect a different set of parameters in order to update their values.
After the mutation runs you can query back all the column data as shown in the querying columns section above.
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. Using both value types can be useful when you want to update columns that do not support simple column values.
mutation {
change_simple_column_value (board_id: 20178755, item_id: 200819371, column_id: "status", value: "1") {
id
}
}
const fetch = require('node-fetch');
var query = "mutation {change_simple_column_value (board_id: 1156871139, item_id: 1156871143, column_id: \"status\", value: \"Working on it\") {id}}";
fetch ("https://api.monday.com/v2", {
method: 'post',
headers: {
'Content-Type': 'application/json',
'Authorization' : 'yourSuperSecretAPIKey'
},
body: JSON.stringify({
'query': "mutation {change_simple_column_value (board_id: 1156871139, item_id: 1156871143, column_id: \"status\", value: \"Working on it\") {id}}"
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { change_simple_column_value (board_id: 1156871139, item_id: 1156871143, column_id: \"status\", value: \"Done\") {id}}"}'
Arguments for Change a Simple Column Value
The following change_simple_column_value()
arguments define which column's value is being changed and what simple value to change to.
Argument | Description |
---|---|
item_id | The item's identifier. |
column_id | The column identifier on your board. |
board_id | The board identifier. |
value | The new simple value of the column. You can find more about simple column values in 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. If you’re using JavaScript, you can use JSON.stringify()
to convert a JSON
object into a string.
After the mutation runs you can query back all the column data as shown in the querying columns section above.
mutation {
change_column_value (board_id: 20178755, item_id: 200819371, column_id: "status", value: "{\"index\": 1}") {
id
}
}
const fetch = require('node-fetch');
var query = "mutation { change_column_value (board_id: 1156871139, item_id: 1156871143, column_id: \"status\", value: \"{\\\"label\\\":\\\"Stuck\\\"}\") {id}}";
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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { change_column_value (board_id: 1156871139, item_id: 1156871143, column_id: \"status\", value: \"{\\\"label\\\":\\\"Stuck\\\"}\") {id}}"}'
Arguments for Change a Column Value
The following change_column_value()
arguments define which column's value is being changed and what JSON value to change to.
Argument | Description |
---|---|
item_id | The item's identifier. |
column_id | The column identifier on your board. |
board_id | The board identifier. |
value | The new value of the column, formatted as JSON. You can find specific examples of JSON values in the Column Types Reference. |
Change Multiple Columns Values
This mutation allows you to update multiple column values of a specific Item (row).
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.
The column_values argument is built in the following form (example with a Text and a Status column):
{\"text\": \"New text\", \"status\": {\"label\": \"Done\"}}
NOTE
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\"}
After the mutation runs you can query back all the column data as shown in the querying columns section above.
mutation {
change_multiple_column_values (item_id: 1234567, board_id: 1156871139, column_values: "{\"status\": {\"index\": 1},\"date4\": {\"date\":\"2021-01-01\"}, \"person\" : {\"personsAndTeams\":[{\"id\":9603417,\"kind\":\"person\"}]}}") {
id
}
}
const fetch = require('node-fetch');
var query = "mutation {change_multiple_column_values (item_id: 1234567, board_id: 1156871139, 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' : 'YourSuperSecretApiKey'
},
body: JSON.stringify({
'query': query
})
})
.then(res => res.json())
.then(res => console.log(JSON.stringify(res, null, 2)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation {change_multiple_column_values (item_id: 1234567, board_id: 1156871139, column_values: \"{\\\"status\\\": {\\\"index\\\": 1},\\\"date4\\\": {\\\"date\\\":\\\"2021-01-01\\\"}, \\\"person\\\" : {\\\"personsAndTeams\\\":[{\\\"id\\\":9603417,\\\"kind\\\":\\\"person\\\"}]}}\") {id}}"}'
Arguments for Change Multiple Columns Values
The following change_multiple_column_values()
arguments define the columns' values being changed and what values to change to.
Argument | Definition |
---|---|
item_id | The item's identifier. |
board_id | The board's identifier. |
column_values | The column values updates. |
Change a Column Title
This mutation allows you to update the title of an existing column.
After the mutation runs you can query back all the column data as shown in the querying columns section above.
mutation {
change_column_title (board_id: 1234567, column_id: "status", title: "new_status") {
id
}
}
const fetch = require('node-fetch');
var query = "mutation { change_column_title (board_id: 1234567, column_id: \"status\", title: \"New_Status\") {id}}";
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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation { change_column_title (board_id: 1248277923, column_id: \"status\", title: \"New_Status\") {id}}"}'
Arguments for Change a Column Title
The following change_column_title()
arguments define which column's title will be changed.
Argument | Definition |
---|---|
column_id | The column's identifier. |
board_id | The board's identifier. |
title | The new title of the column |
Change Column Metadata
This mutation allows you to update the metadata of an existing column. Currently we support updating:
- Title
- Description
After the mutation runs you can query back all the column data as shown in the querying columns section above.
Changing a column's description:
mutation {
change_column_metadata(board_id: 123456789, column_id: "date4", column_property: description, value: "This is my awesome date column"){
id
title
description
}
}
const fetch = require('node-fetch');
var query = "mutation{change_column_metadata(board_id: 123456789, column_id: \"date4\", column_property: description, value: \"This is my awesome date column\"){id title description}}";
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)));
curl --location --request POST 'https://api.monday.com/v2' \
--header 'Authorization: YourSuperSecretApiKey' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation{change_column_metadata(board_id: 123456789, column_id: \"date4\", column_property: description, value: \"This is my awesome date column\"){id title description}}"}'
Arguments for Change Column Metadata
The following change_column_metadata()
arguments define the property being updated and the new value.
Argument | Definition |
---|---|
column_id | The column's identifier. |
board_id | The board's identifier. |
column_property | The property you want to change ('title' or 'description') |
value | The value you want to assign to that property, as a String. |
Updated about 2 months ago