API v2

Introduction

Welcome to monday.com, a collaborative work management platform. monday.com can help you and your team plan and keep track of all tasks or projects, communicate with one another more effectively, and increase transparency amongst your team.

monday.com’s mission is to help teams fulfill their potential and collaborate better. The monday.com API is one of the ways to help your team achieve more together!

What is the monday.com API exactly?

The monday.com API supports read and write (mutating) access to boards, items, and more. It gives you the ability to both view and use any data you have in monday.com outside of the platform. You can use the API to import external data into your monday.com account or trigger actions in monday.com in response to a change in an external software or service.

We’re also working on adding an “app market place” into the monday.com platform. This would give you the ability to build and add entire applications into monday.com. These apps would then be available for all monday.com users to integrate into the platform. This option is not yet supported but it is in our roadmap. If you plan on building a full app, that others can also use within monday.com, please contact us at [email protected]

How does it work?

The monday.com API is based on the GraphQL structure (an alternative to REST based API), which operates on a single URL/endpoint. The monday.com API v2 url is: api.monday.com/v2. As a result, you can use the API to pull and/or alter data about Users, Updates, Items, Boards, Tags and more.

How to get started?

Set up a monday.com account

If you’re not already a monday.com user, the first step is to sign up and create your account.

Authenticate with the API

Once you set up your account, the next step to setting up the API is to authenticate with the Access Tokens. For more information, see the authentication section below.

Using the API

Browse our endpoints and start to query the API. If you’re new to the monday.com API, it’s best to start by learning the basics about Boards, Items, Updates, Users, and Tags.

Using the API can be done by a simple POST request with the query in the request body. We also have code examples in different programming languages in the developers forum of our community.

A simple example of how to access monday.com API using a CURL command:

curl -X POST -H "Content-Type:application/json" -H "Authorization:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -d '{"query":"{boards(limit:1){id name}}"}' "https://api.monday.com/v2/"

Authentication

Before you can start querying the monday.com account with the API, you’ll need to provide valid authentication through an access token. Each user has their own API token, which grants API access to all the boards to which the user has access (i.e they’re subscribed to).

API v2 Token & API Tokens

Currently, monday.com has two active APIs - our “old” (REST-based) and our “new” one (GraphQL). We will gradually deprecate the old version, but for now both of them are available and have different tokens. When using our GraphQL API make sure you’re using the right token which is available under “API v2 Token”.

Accessing your tokens

Log into your monday.com account.
Click on your avatar (picture icon) in the bottom left corner.
Select Admin from the resulting menu (this requires you to have admin permissions).
Go to the API section.
Generate a “API v2 Token”
Copy your token.

*You can always regenerate a new token. Keep in mind it will cause the existing one to expire.

Using tokens

Once you retrieve the token from your monday.com account, you can start making requests with the API. You will need to pass the token to the API in the header of your requests.

Send the API v2 token in the "Authorization" header:

"Authorization:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Rate Limits

The API rate limits are based on complexity level, which is limited to 10,000,000 / minute per account.

Complexity levels are calculated based on the query itself. Each call will have a different level of complexity dependending on the structure of the query. Lower complexity queries are those that query specific objects.

For example, a query for all boards and all users would be calculated by adding together the complexity levels of each of those queries.

For example, a query for all boards and their items returns 1000 boards and 1000 items per board. Complexity would be calculated by multiplying 1000x1000 to get a complexity of 1,000,000.

query {

boards {

items {

}

Rates defaults

Certain queries have default complexities regardless of the results of the query. For example, querying most objects without limits (i.e all boards, items, groups etc.) is calculated as a complexity of 1000. However, there are specific objects, like updates, which have a default complexity of 25.

query {

updates {

}

What happens when exceeding the limit?

The complexity limit starts at 10,000,000 and decreases with each query. Each minute the complexity limit resets to 10,000,000. If an account has exceeded the limit in a certain minute, the query will return an error 4XX which indicated that the account reached the limit.

Complexity limiting

To work efficiently and avoid reaching the limit, it’s recommended to add limits to each part of the query to extract only the data you need and lower the complexity level.

Following up on the example above, you could limit the boards to certain IDs which will decrease the number of results significantly.

query {

updates (ids: [157244624, 9539475, 3209345]) {

items {

}

Complexity nesting

Multiple nesting will also increase the level of complexity in a query. Currently, the maximum number of nested queries allowed is 6.

When calculating complexity of nested queries, the complexity level of each query will be multiplied together. As a result, it is very important to add limits to each query to prevent exceeding the complexity limit.

query {

updates (ids: [157244624, 9539475, 3209345]) {

board_folder_id

permissions

items {

name

creator {

birthday

teams {

name

users {

}

Finding out complexity level

Since accounts are limited by complexity level per minute, understanding the complexity level of each query plays a large role in planning the right queries. The best way to calculate the complexity is to query for complexity as part of your queries.

To see how to query complexity, please see the Querying complexity section.

Using GraphQL

Unlike REST APIs where there is a clearly defined structure of information returned from each endpoint, GraphQL always exposes one endpoint, allowing you to determine the structure of the data that is returned.

The result of each query will be formatted in the same way as the query itself.

In the following section we’re going to have a quick look into to GraphQL components.

Operations

Query - A GraphQL query performs the READ operation and does not change data.

Mutation - To perform all other operations to modify data you will need mutations. You can think of mutations as CUD (Create, Update, Delete) in REST.

Object Types

Object types are a collection of fields, which are used to describe the set of possible data you can query from the API.

query {

}

mutation {

}

Fields

Fields are used to ask for specific properties in objects.

Each object has fields that can be queried by name in order to query for specific properties.

query {

boards {

}

Arguments

You can pass arguments to a query to determine the return value (eg. filtering search results) and narrow down the results to the specific ones you’re after.

In the following example, the object is “boards”, the requested field is “owner”, the argument is “ids”, and the argument value is 201781755.

query {

boards (ids: 157244624){

title

}

GraphQL visual interface - GraphiQL

One of the most powerful parts of GraphQL is its visual interface. GraphiQL is an in-browser tool for writing, validating, and testing GraphQL queries.

Before diving in and starting querying the API, it’s highly recommended to run your queries through the visual interface to make sure they are correct and the data being returned is the data you expect. GraphiQL is available in the Try It Yourself tab.

Variables

Variables can be used to pass dynamic values to our arguments. Variables are written outside of the query string itself, in the variables section, and passed to the arguments.

When we start working with variables, we need to do three things:

Replace the static value in the query with $variableName
Declare $variableName as one of the variables accepted by the query
Pass variableName: value in the separate, transport-specific (usually JSON) variables dictionary

mutation change_column_value($value: JSON!) {

change_column_value (board_id: 157244624,item_id: 9539475, column_id: "status", value: $value) {

}

query variables:

{

"value": "{\"index\": 1}"

}

Querying monday.com entities (object types)

Querying is the way to ask for data, it’s similar to the GET action in REST-based APIs.

In the following sections we’re going to discuss each of the entities you can query and the different data you can extract from each of them. Here is a list of the monday.com entities you can query through the API:

Boards
Items
Items by column values
Updates
Tags
Users
Teams

Boards

monday.com boards are where our users input all of their data and as such it is one of the core components of the platform and one of the main objects with which you will need to be familiar.

The board’s structure is composed of rows (called items), groups of rows (called groups), and columns. The data of the board is stored in the items of the board and in the updates sections of each item. Each board has one or more owners and subscribers.

Additionally, there are three different board types (main, shareable, private) and each board can have different sets of permissions.

Querying boards

Querying boards returns one board or a collection of boards. Boards can receive the following arguments:

Field	Arguments
boards[Board] Get a collection of boards.	limitInt Number of items to get, the default is 25. pageInt Page number to get, starting at 1. ids[Int] A list of boards unique identifiers. board_kindBoardKind The board's kind (public / private / share) stateState The state of the board (all / active / archived / deleted), the default is active. newest_firstBoolean Get the recently created boards at the top of the list

query {

boards (ids: 157244624) {

permissions

}

Board fields

As mentioned above, boards are comprised of different components and when querying a board you can request specific fields to be returned. Each board contains the following fields:

Field	Arguments
board_folder_idInt The board's folder unique identifier.
board_kind!BoardKind The board's kind (public / private / share).
columns[Column] The board's visible columns.
descriptionString The board's description.
groups[Group] The board's visible groups.	ids[String] A list of group unique identifiers.
id!ID The unique identifier of the board.
items[Item] The board's items (rows).	ids[Int] A list of items unique identifiers.
name!String The board's name.
owner!User The owner of the board.
permissions!String The board's permissions.
posString The board's position.
state!State The board's state (all / active / archived / deleted).
subscribers![User] The board's subscribers.
tags[Tag] The board's specific tags.
updates[Update] The board's updates.	limitInt Number of items to get, the default is 25. pageInt Page number to get, starting at 1.

query {

boards (ids: 157244624) {

name

state

board_folder_id

owner {

}

Columns

Columns and items are two core elements of a board. A board is formatted as a table where there are columns and rows called items. In monday.com each column has a specific functionality it enables (ex. a numbers column, a text column, a time tracking column, etc.)

Column fields

Querying columns returns one or a collection of columns. Columns are available for querying through boards and contain the following fields:

Field
archived!Boolean Is the column archived or not.
id!ID The column's unique identifier.
settings_str!String The column's settings in a string form.
title!String The column's title.
type!String The column's type.
widthInt The column's width.

query {

boards (ids: 157244624) {

owner {

}

columns {

title

type

}

Groups

Items are grouped together in units called groups. Each board contains one or multiple groups, and each group can hold one or many items.

Group fields

Querying groups returns one group or a collection of groups in a specific board. Groups are available for querying through boards and contain the following fields:

Field	Arguments
archivedBoolean Is the group archived or not.
color!String The group's color.
deletedBoolean Is the group deleted or not.
id!ID The group's unique identifier.
items[Item] The items in the group.	ids[Int] A list of items unique identifiers.
position!String The group's position in the board.
title!String The group's title.

query {

boards (ids: 157244624) {

groups (ids: status) {

title

color

position

}

Items

monday.com items are another core object in the platform. Items are the objects that hold the actual data within the board, to better illustrate this, you can think of a board as a table and a item as a single row in that table.

Querying items

Querying items returns one or a collection of items. Items can receive the following arguments:

Field	Arguments
items[Item] Get a collection of items.	limitInt Number of items to get, the default is 25. pageInt Page number to get, starting at 1. ids[Int] A list of items unique identifiers. newest_firstBoolean Get the recently created items at the top of the list

query {

items (ids: [157244624, 201781760, 239164869]) {

name

}

Item fields

As mentioned above, items hold the actual data within the board. Each item contains columns in which the different values are stored. Each item contains the following fields:

Field	Arguments
boardBoard The board that contains this item.
column_values[ColumnValue] The item's column values.	ids[String] A list of column ids to return
created_atString The item's create date.
creatorUser The item's creator.
creator_id!String The unique identifier of the item creator.
groupGroup The group that contains this item.
id!ID The item's unique identifier.
name!String The item's name.
stateState The board's state (all / active / archived / deleted).
subscribers![User] The pulses's subscribers.
updated_atString The item's last update date.
updates[Update] The item's updates.	limitInt Number of items to get, the default is 25. pageInt Page number to get, starting at 1.

query {

items (limit: 50) {

name

board {

}

creator {

}

Items By Column Values

Just like in a table, the different values of each item are stored in columns.

Querying items by column values

Querying items by column values searches for items based on their column values and returns data about those specific items.

Unlike other queries, when querying items by column values there are some arguments that must be included, and some arguments that are optional:

Field	Arguments
items_by_column_values[Item] Search items by their column values.	limitInt Number of items to get, the default is 25. pageInt Page number to get, starting at 1. board_id!Int The board's unique identifier. column_id!String The column's unique identifier. column_value!String The column value to search items by. column_typeString The column type. stateState The state of the item (all / active / archived / deleted), the default is active.

query {

items_by_column_values (board_id: 20178755, column_id: "date", column_value: "2019-02-06") {

name

}

Item fields

As mentioned above, items hold the actual data within the board, while the different values of each item are stored in columns. Each item contains the following fields:

The fields available in items by column values are exactly the same as the fields available in “Items”. You can see them here.

Field	Arguments
boardBoard The board that contains this item.
column_values[ColumnValue] The item's column values.	ids[String] A list of column ids to return
created_atString The item's create date.
creatorUser The item's creator.
creator_id!String The unique identifier of the item creator.
groupGroup The group that contains this item.
id!ID The item's unique identifier.
name!String The item's name.
stateState The board's state (all / active / archived / deleted).
subscribers![User] The pulses's subscribers.
updated_atString The item's last update date.
updates[Update] The item's updates.	limitInt Number of items to get, the default is 25. pageInt Page number to get, starting at 1.

query {

items_by_column_values (board_id: 20178755, column_id: "date", column_value: "2019-02-06") {

name

column_values_str

board {

state

board_kind

}

Updates

monday.com updates are additional notes and information added to items outside of the structure of the board. The main form of communication within the platform takes place in the updates section.

Querying updates

Querying updates returns one or a collection of updates. Updates can receive the following arguments:

Field	Arguments
updates[Update] Get a collection of updates.	limitInt Number of items to get, the default is 25. pageInt Page number to get, starting at 1.

query {

updates (limit: 100) {

}

Update fields

As mentioned above, updates are additional information within the items. Each update contains the following fields:

Field
body!String The update's html formatted body.
created_atDate The update's creation date.
creatorUser The update's creator.
creator_idString The unique identifier of the update creator.
id!ID The update's unique identifier.
item_idString The update's item ID.
replies[Reply] The update's replies.
text_bodyString The update's text body.
updated_atDate The update's last edit date.

query {

updates (limit: 100) {

body

}

Field	Arguments
tags[Tag] Get a collection of tags.	ids[Int] A list of tags unique identifiers.

Field
color!String The tag's color.
id!Int The tag's unique identifier.
name!String The tag's name.

Users

Every user in monday.com is a part of an account (i.e an organization) and could be a member or a guest in that account.

Querying users

Querying users returns one or multiple users. Users can receive the following arguments:

Field	Arguments
users[User] Get a collection of users.	ids[Int] A list of users unique identifiers. kindUserKind The kind to search users by (all / non_guests / guests / non_pending). newest_firstBoolean Get the recently created users at the top of the list limitInt Number of users to get

query {

users (kind: non_guests) {

}

User fields

Each user contains the following fields:

Field
account!Account The user's account.
birthdayDate The user's birthday.
country_codeString The user's country code.
created_atDate The user's creation date.
email!String The user's email.
enabled!Boolean Is the user enabled or not.
id!Int The user's unique identifier.
is_guestBoolean Is the user a guest or not.
is_pendingBoolean Is the user a pending user
join_dateDate The date the user joined the account.
locationString The user's location.
mobile_phoneString The user's mobile phone number.
name!String The user's name.
phoneString The user's phone number.
photo_originalString The user's photo in the original size.
photo_thumbString The user's photo in thumbnail size.
teams![Team] The teams the user is a member in.
time_zone_identifierString The user's timezone identifier.
titleString The user's title.
url!String The user's profile url.
utc_hours_diffInt The user’s utc hours difference.

query {

users (ids: [3332456, 8375782, 9304582]) {

created_at

account {

name

}

Teams

Teams are the most efficient way to manage groups of users in monday.com. Teams are comprised of one or multiple users, and every user can be a part of multiple teams (or none).

Querying teams

Querying teams returns one or several of teams. Users can receive the following arguments:

Field	Arguments
teams[Team] Get a collection of teams.	ids[Int] A list of teams unique identifiers.

query {

teams (ids: [9834, 33, 20595]) {

name

}

Team fields

Each team contains the following fields:

Field
id!Int The team's unique identifier.
name!String The team's name.
picture_urlString The team's picture url.
users[User] The users in the team.

query {

teams {

name

picture_url

users {

created_at

phone

}

Me

There is also an option to query the user details of the user whose API key is being used if the API is the personal API key. This is the fastest way to query for the user details (same as users query) of the connected user.

Querying me

The “me field” has the same fields as the Users field.

Field
meUser Get the connected user's information.

query {

me {

is_guest

join_date

}

Complexity

As mentioned in the rate limits section, the amount of API calls each account can perform is limited by complexity per minute. Querying for complexity allows you to determine the complexity of your query and how much of your 1 minute cap will be used.

Querying complexity

Simply add the complexity query to your query and you’ll receive another field which represents the complexity level.

Field
complexityComplexity Get the complexity data of your queries.

Complexity fields

Complexity contains the following fields:

Field
after!Int The remainder of complexity after the query's execution.
before!Int The remainder of complexity before the query's execution.
query!Int The specific query's complexity.

query {

complexity {

query

after

}

users(kind: non_guests) {

name

}

Mutating monday.com entities (object types)

Mutating in GraphQL is the way to modify data, it is the term used to include all non API functions otha than GET. This includes functions such as put, post, and delete that you may be familiar with from REST-based APIs.

Unlike querying, mutating requires adding all the arguments to the mutation. After it runs, you can query the values of the object after the mutation took place.

There are different types of monday.com entities that can be mutated through the API. In the following sections we’re going to dive into each of them, the different data you can mutate, and additional details about how to do so.

Here is a list of the monday.com entities that can be mutated:

Boards
Columns
Groups
Items
Updates
Notifications
Statuses
Tags

Boards

monday.com boards are where our users input all of their data and as such it is one of the core components of the platform and one of the main objects with which you will need to be familiar.

Additionally, there are three different board types (main, shareable, private) and each board can have different sets of permissions.

Create board

Allows you to create a new board. After the mutation runs you can query back all the board data as shown in the Querying boards section.

To see all the available template ID's go to monday.labs and activate the "Developer mode" feature. You will then be able to see the template ID's in the create board from template screen.

Field	Arguments
create_boardBoard Create a new board.	board_name!String The board's name board_kind!BoardKind The board's kind (public / private / share) template_idInt Optional board template id

mutation {

create_board (board_name: "my board", board_kind: public) {

}

Archive board

Below are the list of options to mutate a board. After the mutation runs you can query back all the board data as shown in the Querying boards section.

Field	Arguments
archive_boardBoard Archive a board.	board_id!Int The board's unique identifier

mutation {

archive_board (board_id: 20178755) {

}

Columns

Create column

Allows to add a new column to the different board through the API. After the mutation runs you can query back all the board data as shown in the Querying columns section.

Field	Arguments
create_columnColumn Create a new column in board.	board_id!Int The board's unique identifier. title!String The new column's title. column_typeColumnType The type of column to create.

mutation {

create_column (board_id: 20178755, title: "Work status", column_type: status) {

}

Change column value

The data of each item is stored in columns. The change column value mutation allows you to change the value of a column in 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 to a particular column, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string). To check how to send the data for each column please see changing column values section.

After the mutation runs you can query back all the board data as shown in the Querying columns section.

Field	Arguments
change_column_valueItem Change an item's column value.	item_idInt The item's unique identifier. column_id!String The column's unique identifier. board_id!Int The board's unique identifier. value!JSON The new value of the column.

mutation {

change_column_value (board_id: 20178755, item_id: 200819371, column_id: "status", value: "{\"index\": 1}") {

}

Change multiple column values

This mutation allows you to update multiple columns 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 JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string).

The column_values argument is built in the following form (example with text and status columns):

{\"text\": \"New text\", \"status\": {\"label\": \"Done\"}}

To check how to send the data for each column please see changing column values section.

After the mutation runs you can query back all the board data as shown in the Querying columns section.

Field	Arguments
change_multiple_column_valuesItem Changes the column values of a specific item.	item_idInt The item's unique identifier. board_id!Int The board's unique identifier. column_values!JSON The column values updates.

mutation {

change_multiple_column_values (board_id: 20178755, item_id: 200819371, column_values: "{\"status\": {\"index\": 1}}") {

}

Groups

Items are grouped together in units called groups. Each board contains one or multiple groups, and each group can hold one or many items.

Duplicate group

The duplicate group mutation duplicates a group with all of its items. After the mutation runs you can query back all the group data as shown in the Querying groups section.

Field	Arguments
duplicate_groupGroup Duplicate a group.	board_id!Int The board's unique identifier. group_id!String The group's unique identifier. add_to_topBoolean Should the new group be added to the top. group_titleString The group's title.

mutation {

duplicate_group (board_id: 20178755, group_id: "today", add_to_top: true) {

}

Create group

The create group mutation creates a new empty group. After the mutation runs you can query back all the group data as shown in the Querying groups section.

Field	Arguments
create_groupGroup Creates a new group in a specific board.	board_id!Int The board's unique identifier. group_name!String The name of the new group.

mutation {

create_group (board_id: 20178755, group_name: "new group") {

}

Archive group

The archive group mutation archives a group with all of its items. After the mutation runs you can query back all the group data as shown in the Querying groups section.

Field	Arguments
archive_groupGroup Archives a group in a specific board.	board_id!Int The board's unique identifier. group_id!String The group's unique identifier.

mutation {

archive_group (board_id: 20178755, group_id: "today") {

archived

}

Delete group

The delete group mutation deletes a group with all of its items. After the mutation runs you can query back all the group data as shown in the Querying groups section.

Field	Arguments
delete_groupGroup Deletes a group in a specific board.	board_id!Int The board's unique identifier. group_id!String The group's unique identifier.

mutation {

delete_group (board_id: 20178755, group_id: "today") {

deleted

}

Items

Create item

You can create a new item in the different boards through the API with the create item mutation.

The data of each item is stored in the board’s columns, each of which holds a particular piece of information. Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data to a particular column, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string). To check how to send the data for each column please see changing column values section.

After the mutation runs you can query back all the board data as shown in the Querying items section.

Field	Arguments
create_itemItem Create a new item.	item_nameString The new item's name. board_id!Int The board's unique identifier. group_idString The group's unique identifier. column_valuesJSON The column values of the new item.

mutation {

create_item (board_id: 20178755, group_id: "today", item_name: "new item") {

}

Move item to group

This mutation allows one to move a item between groups in the same board. After the mutation runs you can query back all the board data as shown in the Querying items section.

Field	Arguments
move_item_to_groupItem Move an item to a different group.	item_idInt The item's unique identifier. group_id!String The group's unique identifier.

mutation {

move_item_to_group (item_id: 20178755, group_id: "today") {

}

Archive item

This mutation allows one to archive a single item. After the mutation runs you can query back all the board data as shown in the Querying items section.

Field	Arguments
archive_itemItem Archive an item.	item_idInt The item's unique identifier.

mutation {

archive_item (item_id: 20178755) {

}

Delete item

This mutation allows one to delete a single item. After the mutation runs you can query back all the board data as shown in the Querying items section.

Field	Arguments
delete_itemItem Delete an item.	item_idInt The item's unique identifier.

mutation {

delete_item (item_id: 20178755) {

}

Updates

monday.com updates are additional notes and information added to items outside of the structure of the board. The main form of communication within the platform takes place in the Querying updates section.

Create update

The create update mutation allows one to add an update to a item. After the mutation runs you can query back all the board data as shown in the Querying updates section.

Field	Arguments
create_updateUpdate Create a new update.	body!String The update text. item_idInt The item's unique identifier.

mutation {

create_update (item_id: 20178755, body: "This update will be added to the item") {

}

Notifications

Notifications are sent in the platform in response to various triggers such as due dates, updates, and more. By default, each notification within the platform will also be sent out as an email to the recipient (this can be customized in the user’s profile settings).

Create notification

The create notification mutation allows to trigger a notification within the platform (will also send out an email if the recipient's email preferences allow). Keep in mind that notifications are async and you will not be able to query their ID's back after sending then out.

Field	Arguments
create_notificationNotification Create a new notification.	text!String The notification text. user_id!Int The user's unique identifier. target_id!Int The target's unique identifier. target_type!NotificationTargetType The target's type (Project / Post) payloadJSON The notification payload.

mutation {

create_notification (user_id: 105939, target_id: 674387, text: "This is a notification", target_type: project) {

text

}

Field	Arguments
create_or_get_tagTag Create a new tag or get it if it already exists.	tag_nameString The new tag's name. board_idInt The private board id to create the tag at (not needed for public boards)

Webhooks

monday.com webhooks integration allows you to subscribe to events on your boards, and get notified by an HTTP post request to a specified URL with the event information as a payload.

For more information about webhooks, and the webhooks payload Click here.

Create a webhook

The mutation allows you to create a new webhook. After the mutation runs, the webhook will report the wanted event on the specific board given to the wanted URL.

The URL will have to pass a verification test, where we will send a json POST body request containing a challenge field. We expect you to return the token as a challenge field on your response json body to that request.

Field	Arguments
create_webhookWebhook Create a new webhook.	board_id!Int The board's unique identifier. url!String The webhook URL. event!WebhookEventType The event to listen to (change_column_value / create_item / create_update)

mutation {

create_webhook ( board_id: 12593, url: "https://www.webhooks.my-webhook/test", event: create_item) {

board_id

}

Delete a webhook

The delete webhook mutation deletes a webhook. After the mutation runs it will no longer report events to the URL given.

Field	Arguments
delete_webhookWebhook Delete a new webhook.	id!Int The webhook's unique identifier.

mutation {

delete_webhook ( id: 12) {

board_id

}

Changing item column values

Every monday.com board has one or more columns, each of which holds a particular piece of information. Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data to a particular column, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string).

You will mainly need to change item column values in 2 scenarios - when updating the value of an item using the change_column_value mutation, or when creating a new item by using the create_item mutation and setting its values on creation.

Item name column

To update the item's name, send a string of 1 to 255 characters.

Raw JSON - use this in your column values variables:

JSON.stringify("My item");

JSON string - use this in the GraphiQL editor:

"\"My item\""

Text column

To update the text column send a string.

Raw JSON - use this in your column values variables:

JSON.stringify("Sample text");

JSON string - use this in the GraphiQL editor:

"\"Sample text\""

Long text column

To update the long text column, send a string up to 2000 characters with the key “text”.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "text": "Sample text"
});

JSON string - use this in the GraphiQL editor:

"{\"text\":\"Sample text\"}"

Number column

To update the number column send a string containing a float or int.

Raw JSON - use this in your column values variables:

JSON.stringify("3");

JSON string - use this in the GraphiQL editor:

"\"3\""

Status column

Each status column is a collection of indexes and their corresponding label. 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. You can only use existing statuses, and if the label you sent doesn’t exist you will get an error containing all the existing statuses and their indexes.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "index": 0
});

JSON string - use this in the GraphiQL editor:

"{\"index\":0}"

Raw JSON - use this in your column values variables:

JSON.stringify({
  "label": "Done"
});

JSON string - use this in the GraphiQL editor:

"{\"label\":\"Done\"}"

Each dropdown column is a collection of ids and their corresponding label. To update a dropdown column, send the id of the label you want to set. If you don’t know the id of the label you’re trying to set, you can send the label text instead. You can only use existing labels, and if the label you sent doesn’t exist you will get an error containing all the existing labels and their ids.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "id": 1
});

JSON string - use this in the GraphiQL editor:

"{\"id\":1}"

Raw JSON - use this in your column values variables:

JSON.stringify({
  "label": "My label"
});

JSON string - use this in the GraphiQL editor:

"{\"label\":\"My label\"}"

Person column

To update a person column, send the ID of the user.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "id": 235326
});

JSON string - use this in the GraphiQL editor:

"{\"id\":235326}"

Team column

To update a team column send the ID of the team. The ID of a specific team can be found by using the teams query, checking which teams a particular user is a part of (with the User object), or opening the team’s page in monday.com and copying the number at the end of the URL.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "team_id": 51166
});

JSON string - use this in the GraphiQL editor:

"{\"team_id\":51166}"

People column

To update a people column, send an array with the people or teams you want to add to the column. Each item in the array should include the ID of the person/team, and a string signifying whether the item is a person or a team.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "personsAndTeams": [
    {
      "id": 4616627,
      "kind": "person"
    },
    {
      "id": 4616666,
      "kind": "person"
    },
    {
      "id": 51166,
      "kind": "team"
    }
  ]
});

JSON string - use this in the GraphiQL editor:

"{\"personsAndTeams\":[{\"id\":4616627,\"kind\":\"person\"},{\"id\":4616666,\"kind\":\"person\"},{\"id\":51166,\"kind\":\"team\"}]}"

World clock column

To update a world clock column, send the timezone of the user as a string in continent/city form. You can get the list of available timezones here.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "timezone": "Europe/London"
});

JSON string - use this in the GraphiQL editor:

"{\"timezone\":\"Europe/London\"}"

Country column

To update a country column send the iso-2 country code (2 letter code) and the country name. You can get the list of available countries here.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "countryCode": "US",
  "countryName": "United States"
});

JSON string - use this in the GraphiQL editor:

"{\"countryCode\":\"US\",\"countryName\":\"United States\"}"

Email column

To update an email column, send the email address in the email field. You can also pass display text in the text field.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "email": "[email protected]",
  "text": "my email"
});

JSON string - use this in the GraphiQL editor:

"{\"email\":\"[email protected]\",\"text\":\"my email\"}"

Phone column

To update a phone column send the phone number (digits only) in a string and the iso-2 country code (2 letter code). You can get the list of available countries here.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "phone": "11231234567",
  "countryShortName": "US"
});

JSON string - use this in the GraphiQL editor:

"{\"phone\":\"11231234567\",\"countryShortName\":\"US\"}"

Link column

To update a link column, write the URL (including http/https) in the url field. You can also pass display text in the text field.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "url": "http://monday.com",
  "text": "go to monday!"
});

JSON string - use this in the GraphiQL editor:

"{\"url\":\"http://monday.com\",\"text\":\"go to monday!\"}"

Date column

To update a date column, send the date as a string in a YYYY-MM-DD format. You can also add a time by passing a “time” field in HH:MM:SS format.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "date": "2019-06-03",
  "time": "13:25:00"
});

JSON string - use this in the GraphiQL editor:

"{\"date\":\"2019-06-03\",\"time\":\"13:25:00\"}"

Timeline column

To update a timeline column, send the start and end dates in a YYYY-MM-DD format, where the start date is “from” and the end date is “to”.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "from": "2019-06-03",
  "to": "2019-06-07"
});

JSON string - use this in the GraphiQL editor:

"{\"from\":\"2019-06-03\",\"to\":\"2019-06-07\"}"

Tags column

To update a tags column, send the tag ID’s in an array.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "tag_ids": [
    295026,
    295064
  ]
});

JSON string - use this in the GraphiQL editor:

"{\"tag_ids\":[295026,295064]}"

Hour column

To update an hour column, send the hour and minute in 24-hour format.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "hour": 16,
  "minute": 42
});

JSON string - use this in the GraphiQL editor:

"{\"hour\":16,\"minute\":42}"

Week column

To update a week column send the start and end dates in a YYYY-MM-DD format. Date must be 7 days apart (inclusive of the first and last date) and start at the beginning of the work week defined in the account.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "week": {
    "startDate": "2019-06-10",
    "endDate": "2019-06-16"
  }
});

JSON string - use this in the GraphiQL editor:

"{\"week\":{\"startDate\":\"2019-06-10\",\"endDate\":\"2019-06-16\"}}"

Checkbox column

To check the box in the checkbox column, send a 'checked' field with true. To uncheck the box remove the column value.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "checked": "true"
});

JSON string - use this in the GraphiQL editor:

"{\"checked\":\"true\"}"

Rating column

To update a rating column send a number between 1 and your rating scale (can be updated in the column settings).

Raw JSON - use this in your column values variables:

JSON.stringify({
  "rating": 5
});

JSON string - use this in the GraphiQL editor:

"{\"rating\":5}"

Auto calculated columns

Some of the columns in monday.com are auto calculated based on other properties. You cannot update the following columns:

Progress tracking column
Auto number column
Item ID column
Last updated column
Creation log column
Formula column

Removing column values

To remove a column value (delete the excisting value) send an empty string for text or number columns or an empty object for more complex columns.

Raw JSON - use this in your column values variables:

JSON.stringify({});

JSON string - use this in the GraphiQL editor:

"{}"

Introduction

What is the monday.com API exactly?

How does it work?

How to get started?

Set up a monday.com account

Authenticate with the API

Using the API

Authentication

API v2 Token & API Tokens

Accessing your tokens

Using tokens

Rate Limits

Rates defaults

What happens when exceeding the limit?

Complexity limiting

Complexity nesting

Finding out complexity level

Using GraphQL

Operations

Object Types

Fields

Arguments

GraphQL visual interface - GraphiQL

Variables

Querying monday.com entities (object types)

Boards

Querying boards

Board fields

Columns

Column fields

Groups

Group fields

Items

Querying items

Item fields

Items By Column Values

Querying items by column values

Item fields

Updates

Querying updates

Update fields

Tags

Querying tags

Tag fields

Users

Querying users

User fields

Teams

Querying teams

Team fields

Me

Querying me

Complexity

Querying complexity

Complexity fields

Mutating monday.com entities (object types)

Boards

Create board

Archive board

Columns

Create column

Change column value

Change multiple column values

Groups

Duplicate group

Create group

Archive group

Delete group

Items

Create item

Move item to group

Archive item

Delete item

Updates

Create update

Notifications

Create notification

Tags

Create or get tag

Webhooks