This article will walk you through making some basic operations using the monday.com GraphQL API, and then ramp up to more complicated queries. Go through it as quickly or slowly as you'd like. You can download all the sample code here.

 

What is the monday.com API?

The monday.com API allows external applications to retrieve and edit data from the monday.com work OS.

For example, you can use the API to sync data between monday.com and another platform, so that your team's actions on monday.com are synced with the other tools you use.

Our API is built on GraphQL, which is a little different from the REST APIs you might be used to. Our GraphQL schema defines objects and fields that can be queried via our API.

 

Topics covered

• What is GraphQL and why is it useful
• How to structure a request to the monday.com API
• How to write simple queries
• How to write mutations to change data in monday.com

 

Prerequisites

• A working PHP environment
• An active monday.com account (sign up at monday.com if you haven't already)
• A basic understanding of web APIs and HTTP requests
• A basic understanding of PHP 

 

Structuring your API requests

There are a few things to keep in mind when you're building your first API call:

• Request Structure: all requests to the API must be POST requests. Queries must conform to our GraphQL schema
• Authentication: all requests to the API should include an authentication token in the request header. Learn how to get your API key here. 
• Request Body: all requests to the API should have a JSON-formatted body. The only exception is file uploads, which should be multipart requests.

 

Making your first API call

The monday.com API can retrieve objects and their associated fields from the Work OS.

Let's begin by retrieving a list of boards, along with their names and board IDs.To do this, we will specify the "boards" object in our query, and then run the following script on your PHP server: 

<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = '{ boards { id name } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
  'method' => 'POST',
  'header' => $headers,
  'content' => json_encode(['query' => $query]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

Navigate to your server's URL in your browser. You should see a response that contains a list of boards, like so:

Notice that the returned data is JSON, so you can serialize it into an array and do whatever you want with it. Iterate through it; construct a tree; go nuts.

 

Getting data from specific items

Now let's take advantage of GraphQL's flexibility and return the item's name and columns, as well as the type, title, and ID of each column.

Here's our query:

{ items (ids: [1234567890, 9876543210, 1122334455]) {
    name
    column_values {
      column {
        title
        id
        type
      } 
    } 
  } 
}

Following the example from before, run this on your PHP server:

<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = '{items(ids:[1234567890, 9876543210, 1122334455]) { name column_values { column { title id text } } } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
  'http' => [
    'method' => 'POST',
    'header' => $headers,
    'content' => json_encode(['query' => $query]),
  ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

You will receive a much richer set of data with this query.

 

Creating a new item

In this section, we will write a mutation to create a new item on your board.

Mutations are operations that add or update data, and also return fields on the object that was created or changed. The data you are changing is passed as arguments to the mutation.

Here's the query we will use:

mutation {
  create_item (board_id: YOUR_BOARD_ID_HERE, item_name: "WHAT IS UP MY FRIENDS!") {
  id
} }

And here's the code for making this request. Notice that we are using double-quotes for the "item_name" argument, to differentiate the inner string from the query itself.

<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = 'mutation{ create_item (board_id:YOUR_BOARD_ID, item_name:"WHAT IS UP MY FRIENDS!") { id } }';
$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => $headers,
 'content' => json_encode(['query' => $query]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

When the mutation is successful, you will get a response that contains the ID of the item you just created:

 

Creating a new item using GraphQL variables

So far, we have been writing queries and mutations with hard-coded values in them. That is, if I wanted to change the board I'm creating an item on I'd have to slice and dice the query string, which can be costly.

However, we can dynamically populate arguments in our query using GraphQL variables. We pass the variables as a JSON object, and GraphQL will dynamically insert the variables into our query!

We need to declare the type of the variables in our query and pass the variables as a separate JSON object inside our API request.

This is what that looks like in action:

<?php
$token = 'YOUR_TOKEN_HERE';
$apiUrl = 'https://api.monday.com/v2';
$headers = ['Content-Type: application/json', 'Authorization: ' . $token];

$query = 'mutation ($myItemName: String!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName) { id } }';
$vars = ['myItemName' => 'Hello world!'];

$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => $headers,
 'content' => json_encode(['query' => $query, 'variables' => $vars]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

Like before, a successful mutation will return the ID of the item you created.

 

Creating a new item with column values populated

In our final example, we will create a new item and define the values for each of its columns.

Our GraphQL schema defines a set of column values as a JSON string (key-value pairs). The keys of the column_values object must be column IDs, and the values must be structured depending on the type of the column.

This particular example updates a status and date column. You can set up a board for this example by using our "Start from scratch" template.

<?php
$query = 'mutation ($myItemName: String!, $columnVals: JSON!) { create_item (board_id:YOUR_BOARD_ID, item_name:$myItemName, column_values:$columnVals) { id } }';
$vars = ['myItemName' => 'Hello world!', 
  'columnVals' => json_encode([
    'status' => ['label' => 'Done'], 
    'date4' => ['date' => '1993-08-27']
])];

$data = @file_get_contents($apiUrl, false, stream_context_create([
 'http' => [
 'method' => 'POST',
 'header' => $headers,
 'content' => json_encode(['query' => $query, 'variables' => $vars]),
 ]
]));
$responseContent = json_decode($data, true);

echo json_encode($responseContent);
?>

Congratulations! You have completed this tutorial.

 

Treat yourself!

You deserve it. 🔮​ 

 

 

If you have any questions, please reach out to our team right here. We’re available 24/7 and happy to help.