CommunityApps FrameworkAPI Playground

Columns

Suggest Edits

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 !Boolean

Whether the column is archived or not.

id !ID

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 Int

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 !Int

The board's unique identifier.

title !String

The new column's title.

column_type !ColumnType

The type of column to create (the available column types al listed below).

defaults JSON

The new column's defaults.

description String

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 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: 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 !int

The 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

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 !int

The 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.

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 !Int

The item's identifier.

board_id !Int

The board's identifier.

column_values !JSON

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 !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:

  • 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 !String

The column's identifier.

board_id !Int

The board's identifier.

column_property !ColumnProperty

The property you want to change ('title' or 'description')

value !String

The value you want to assign to that property, as a String.

Updated about 2 months ago

Did this page help you?