Part 3: Writing to Monday with API calls

Ever watched the X-Men movies and thought, “I want to be like them one day…” Well now’s your chance! Today, we’re going to learn how to mutate!?

(With Monday.com API calls… oh yeah!)

This article will walk you through harnessing Monday.com’s API to create new items, groups, and boards and equip you with necessary tools to take full advantage of Monday.com functionality. If you are new to making API calls to Monday.com or simply want a refresher, please refer to the previous post here.?

Now, equipped with your API token and an overview of querying from Monday.com, you are ready to learn how to write to Monday.com using API calls!?

Creating a New Item

Before you can create a new item, there are a few properties you need to find: the board ID, the group ID, and the column IDs that you want to fill in.?

After navigating to the board you wish to write to, you can find its ID by examining the URL. You should see “/boards/” followed by a long number. That number is your board ID.

Next, we want to find the column values. When using developer mode, clicking on the three-dot menu for each column displays the column ID.?

To turn on developer mode, click on your user profile and navigate to monday.labs. Next, scroll or use the search bar to find “Developer Mode” and press “Activate.” This will grant access to tools such as the column IDs.

Finally, finding the group ID is the most complicated. You can do this in two ways – an API call to Monday or via Make.com:

1. This API call will retrieve the ID and title of each group on the specified board:

2. If you are already familiar with Make.com automations and have successfully created a connection between Make.com and Monday.com, you can utilize Make.com to find your desired group ID in the following way: First, select Monday.com’s “Create an Item” module in a Make.com scenario. Select your desired board and group from the dropdown menu. By toggling “Map,” Make.com will display the board and group IDs. It might look something like this:

Now that you have the necessary identifiers to properly place your new item into your workspace, let’s talk about creating your query.?

This query, the “write” kind of query, is going to look fairly similar to the “read” kind of query we used to retrieve information from Monday in part 2 of this series. However, there are some key differences we’ll examine now.?

Here’s an example of a “write” query that creates a new item:

We use the “mutation” keyword instead of the “query” keyword to begin our query. Then, the?

create_item object takes a series of arguments that specify the details of our new item: the?

board_id of the board it will appear on, the group_id of the group it will belong to, its?

item_name, and its?

column_values. The column_values argument is probably the hardest to format, so we’ll take a second to break it down here.?

Basically, column_values is its own dictionary-type object whose keys are the column_ids and whose values are the new item’s values in each column. However, the additional nuance is that not only does the entire column_values dictionary have to be in quotation marks, so does each key and each value (according to JSON rules), which leads to all the \" escape characters in the example. (Tip: if you ever get a parse error with this query, there’s a good chance it’s because you need more escape backslashes!) Here, we’re setting the item’s value in the column with ID “date4” to be “2023-05-25”. The last thing the query is doing is returning the id of the newly created item; that’s what the id field in curly brackets signals. Including the API-call framework, the full example is:

Now that we have reviewed the structure of column_values, we can discuss writing multiple column values. As the dictionary corresponding to column_values must have quotation marks around each of its keys and their values, we can either extend the dictionary as seen in the code snippet above or use JSON.stringify().?

To extend the dictionary, we concatenate new key-value pairs with the previous ones using commas. Together, the query will follow this structure in Javascript:

let query = `mutation { 
    create_item (
        board_id: ${BOARD_ID}, 
        group_id: "${GROUP_ID}", 
        item_name: "testing", 
        column_values: \"{\\\"date4\\\":\\\"2023-05-25\\\",\\\"text__0\\\":\\\"sample text\\\",\\\"numbers__1\\\":\\\"10\\\"}\"
    ) { id }
}`;        

This example allows us to create a new item called “testing” that has “2023-05-25”, “sample text”, and “10” in the “date4”, “text__0”, and “numbers__1” columns respectively. If you run into errors with this format, try keeping the column_values dictionary in one line rather than using line breaks to separate each key-value pair.?

While the above method can be manageable for a few column values, it is not sustainable when we have a large number of columns or need to frequently change values. It may even be difficult to understand after some time away from your javaScript file. This is why the function JSON.stringify() comes in handy.

Using JSON.stringify()

With this tool at our disposal, we can use a javaScript object to store our column IDs and the values we want to write in. Then, to construct the column_values dictionary as previously described, we can call JSON.stringify() on our columnValues object twice. This ensures that the appropriate number of backslashes appear in our query string. Below, we have recreated the previous example using JSON.stringify(). Remember that each key corresponds to the column ID of our target column.?

Javascript

let columnValues = {
        date4: "2023-05-25",
        text__0: "sample text",
        numbers__1: "10",
      };

let query = `mutation { 
    create_item (
        board_id: ${BOARD_ID}, 
        group_id: "${GROUP_ID}", 
        item_name: "testing", 
        column_values: ${JSON.stringify(JSON.stringify((columnValues)))}
    ) { id }
}`;        

Using this method, we can clearly see which values we are writing into each column and we can easily append other columns and their desired values without navigating the numerous backslashes needed.

Deleting Objects with Monday API

Deleting an item is much easier, especially now that we’ve encountered the mutation keyword. You just need to know the ID of the item you want to delete. Here’s the structure:

That’s it! Pretty simple now that we get what’s going on, right?

There are several other “write”-type operations you might want to perform via an API call, and we can’t cover everything, but we’re going to show examples of how to create a new board and a new group, and then provide external resources to help you tackle any other kind of operation you might require.

Create New Groups and Boards on Monday.com

Creating a board is also pretty simple. Here’s a barebones example:

Right now, we’re only defining the board_name and board_kind, but you can add more arguments if you want to specify a few more details about your board, including description and workspace_id – the entire list of possible arguments can be found in the developer docs here.

In addition, the code above returns the new board’s id (which is automatically generated by monday and is not something you can choose).

Creating a group is slightly more complicated since there are more things we need to control for (what board it goes on, where on the board it goes), but it’s nothing we can’t handle:

This “mutation” query creates a new group on the board with ID 1234567890, named “new group,” directly above the group with ID “test group”. The relative_to and position_relative_method arguments work together in this way to determine where on the board the new group is placed. (The two options for position_relative_method are before_at and after_at, which both work in self-explanatory ways.) Furthermore, this API call also returns the id of the new group.

Okay, that’s all we’re going to cover in this post, but if you’re curious about what else you can do with mutation queries in the Monday API, check out their API reference here – it gives detailed explanations (with examples) for how to do many different kinds of “read” and “write” queries. Good luck with your projects, and don’t get discouraged – now you’ve learned the fundamental framework and the rest is just garnish… admittedly occasionally frustrating but garnish all the same.