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.

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

Columns are available for querying through parent items. They must be nested within another query, like a board. You cannot use them at the root of your query.

Querying columns will return either one or a collection of columns.

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)));

You can find the Postman request to get column IDs from a board here.

Fields

Columns contain the following fields that will determine the data returned.

FieldField Description
archived Boolean!Whether the column is archived or not.
ids [Int]The column's identifier, unique only to its board.
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 in a string form.
title String!The column's title.
description String!The column's description.
type String!The column's type.
width IntThe column's width.

Columns mutations

Required scope: boards:write

Create a column

This mutation will create a column on a board within the account. 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)));

You can find the Postman request to create a column here.

Arguments for create a column

The following arguments define the new column's characteristics.

ArgumentDescription
board_id Int!The board's unique identifier.
title String!The new column's title.
column_type ColumnTypeThe type of column to create. Check out our list of available column types.
defaults JSONThe new column's defaults.
description StringThe column's description.

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 your create_item(), create_subitem() and change_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: 12345678, item_id: 987654321, column_id: "status", value: "Working on it") {
        id
    }
}
const fetch = require('node-fetch');

var query = "mutation {change_simple_column_value (board_id: 12345678, item_id: 987654321, 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: 12345678, item_id: 987654321, column_id: \"status\", value: \"Working on it\") {id}}"
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

You can find the Postman request to change a simple column value here.

Arguments for change a simple column value

The following arguments define which column's value is being changed and what simple value to change to.

ArgumentDescription
item_id IntThe item's identifier.
column_id String!The column identifier on your board.
board_id Int!The board identifier.
value String!The new simple value of the column. You can find more about simple column values in Column Types Reference
create_labels_if_missing BooleanCreates status/dropdown labels if they are missing. This requires permission to change the board structure.

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: 12345678, item_id: 987654321, column_id: "status", value: "{\"index\": 1}") {
        id
    }
}
const fetch = require('node-fetch');

var query = "mutation { change_column_value (board_id: 12345678, item_id: 987654321, 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)));

You can find the Postman request to change a column value here.

Arguments for change a column value

The following arguments define which column's value is being changed and what JSON value to change to.

ArgumentDescription
item_id IntThe item's identifier.
column_id String!The column identifier on your board.
board_id Int!The board identifier.
value JSON!The new value of the column, formatted as JSON. You can find specific examples of JSON values in the Column Types Reference.
create_labels_if_missing BooleanCreates status/dropdown labels if they are missing. This requires permission to change the board structure.

Change multiple column 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: 987654321, 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: 987654321, 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)));

Arguments for change multiple columns values

The following arguments define the columns' values being changed and what values to change to.

ArgumentDefinition
item_id IntThe item's identifier.
board_id Int!The board's identifier.
column_values JSON!The column values updates.
create_labels_if_missing BooleanCreates status/dropdown labels if they are missing. This requires permission to change the board structure.

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)));

Arguments for change a column title

The following arguments define which column's title will be changed.

ArgumentDefinition
column_id String!The column's identifier.
board_id Int!The board's identifier.
title String!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 both the title and description.

After the mutation runs you can query back all the column data as shown in the querying columns section above.

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)));

Arguments for change column metadata

The following arguments define the property being updated and the new value.

ArgumentDefinition
column_id String!The column's identifier.
board_id Int!The board's identifier.
column_property ColumnPropertyThe property you want to change: title or description.
value StringThe value you want to assign to that property, as a String.

Delete a column

The delete_column mutation allows you to delete a single column from a board.

mutation {
  delete_column (board_id: 123456789, column_id: "status") {
    id
  }
}

Arguments for delete a column

The following arguments determine which column will be deleted.

ArgumentDescription
column_id String!The column's unique identifier.
board_id Int!The board's unique identifier.

๐Ÿ“˜

Have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Donโ€™t forget to search before opening a new topic!