The status column represents a label designation for your item(s). It can be used to denote the status of a particular item, or hold any other labelling for the item. Each status column is a collection of indexes and their corresponding labels.

Check out our help center to learn more about the status column.

You can also find the full map of Index values and their corresponding colors on the Status Index Value Map.

Reading the status column

You can return the data in a status column in two different formats. The text field will return the data as a simple string, and the value field will return the data as a JSON string.

Here is an example payload showing both fields:

{
  "text": "Working on it",
  "value": "{\"index\":0,\"post_id\":null,\"changed_at\":\"2021-07-21T12:00:00.000Z\"}"
}

Updating the status column

You can update a status column with both a simple string and a JSON string.

Simple strings

To update a status column, send the index of the status you want to set. If you don’t know the index of the label you’re trying to set, you can send the label instead.

If you don't specify create_labels_if_missing: true in your query, the labels you send that don't exist already will not get created and your query will get an error containing all the existing labels and their indexes.

For example: "0" or "Done"

JSON

To update a status column with a JSON string, send the index of the status you want to set. If you don’t know the index of the label you’re trying to set, you can send the label instead.

If you don't specify create_labels_if_missing: true in your query, the labels you send that don't exist already on the board will not get created, and your query will get an error containing all the existing labels and their indexes.

For example: "{\"label\":\"Done\"}" or "{\"index\":0}"

Code example

mutation {
  change_multiple_column_values(item_id:11111, board_id:22222, column_values: "{\"status15\" : {\"label\" : \"Done\"}}") {
    id
  }
}
fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    query : "mutation ($myBoardId:Int!, $myItemId:Int!, $myColumnValues:JSON!) { change_multiple_column_values(item_id:$myItemId, board_id:$myBoardId, column_values: $myColumnValues) { id }}",
    variables : JSON.stringify({
      myBoardId: YOUR_BOARD_ID,
      myItemId: YOUR_ITEM_ID,
      myColumnValues: "{\"status15\" : {\"label\" : \"Done\"}}"
    })
  })
})
curl "https://api.monday.com/v2" \
-X POST \
-H "Content-Type:application/json" \
-H "Authorization:MY_API_KEY" \
-d '{"query":"mutation{change_multiple_column_values(item_id:162169283, board_id:162169280, column_values:\"{\\\"status15\\\" : {\\\"label\\\" : \\\"Done\\\"}}\"){name}}"}'

Index values and color mapping

As mentioned above, you can use both Index and Label values when using JSON formatting in your Mutation calls to update the Status column.

  • change_column_value
  • change_multiple_column_values
  • create_item,create_subitem

By default, every index value matches a specific color. For example, the Green status has the index 1. Here's a full list
of the indexes and matching values.

When you create a new Status label, it will follow the default index value and its index will not change. However, the color of a status label can be changed. Therefore, you cannot assume a label’s color and index will always match.

Take the following example:

Index: 2 will have a color value of #e2445c. Thus, using this index value will set the Status column value to a Red-shadow color, as shown below:

512512

And on the board, this will appear as such:

512512

The color values are not static and can be changed within the Status column labels. You can find more info on this here.

Then, the index value will remain the same, but the color value will be changed. For example, if I chose Black as the new color, this is how the color value would appear in the API:

512512

And this is how the item would appear on the board:

512512

As such, using index values does not guarantee that you will populate the same color values across multiple boards.

If you encounter a mismatch of index values when sending data between boards in your account, we recommend changing the color of the labels back to the default values manually.

📘

Do you 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!


Did this page help you?