> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voxworks.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Monday.com Integration

> Trigger Voxworks calls from a Monday.com board and write call results back onto the board item, using an API key connection and the Automations pipeline.

## What is the Monday.com integration?

Monday.com is a **project\_management**-category integration, connected with an API key. On the Integrations page its card description reads: "Trigger outbound calls from Monday.com boards and sync call results back" — which is exactly the two directions this page covers:

* **Inbound** — start a Voxworks call from a Monday.com board item, using the Voxworks REST API and an API key you generate in Voxworks.
* **Outbound (Integration Sync)** — after a call finishes, write the results (summary, status, duration, and so on) back onto the Monday.com item as column values, using an **Automation**.

Unlike the calendar providers, Monday.com has no dedicated step in the script editor's tool picker — connecting it doesn't add a new tool to your scripts. Both directions run outside the call, through the REST API and the Automations pipeline described below.

<Note>
  On the integration card and in Integration Settings, Monday.com's category badge reads literally **project\_management** rather than a friendly label like "CRM" or "Calendar" — that's a known display quirk, not a setting you can change.
</Note>

<Note>
  Integrations are typically built out for specific clients, so the full functionality of Monday.com's interface might not be available. If your team needs additional features from this integration, contact the Voxworks team directly to discuss what can be added.
</Note>

***

## Connecting Monday.com

1. In the sidebar under **Admin**, open **Integrations**.
2. In the **Available Integrations** section, find the **Monday.com** card.
3. Click **Connect**. The **Connect Monday.com** dialog opens: "Enter your Monday.com API key to establish the connection."
4. Paste your key into the **API Key** field and click **Connect**.

| Field   | Required | Description                                                                                                                                                                                                                                                                                 |
| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API Key | Yes      | Your Monday.com API key (type `string`, example `eyJhbGciOiJIUzI1NiJ9.example-token`). The dialog notes: "Your API key will be securely encrypted and stored. You can find your API key in your Monday.com account settings." The **Connect** button stays disabled until a key is entered. |

While the key is being saved the button reads **Connecting...**. On success the Monday.com card moves to the **Connected Integrations** section with a green **Connected** badge. Opening the gear icon on the card shows **Integration Settings** — **Status** (Connected/Error badges plus an **API Key** auth-type badge), **Connection Details** (when you connected, and a masked view of the key), and **Available Tools**, which reads "No tools are currently available for this integration" — expected, since Monday.com works through the API and Automations rather than a script tool.

***

## Triggering calls from Monday.com

Monday.com's own Developer Center supports a "Make a Voxworks Call" custom automation-recipe action for boards, so you could trigger a call directly from a Monday.com automation without leaving Monday.com. **That marketplace action is coming soon and isn't available yet.**

Today, trigger calls from Monday.com with a generic Monday.com automation recipe (for example, a webhook/integration block that fires when an item enters a status or group) that sends an HTTP request to the Voxworks REST API's Create Phone Call endpoint.

### Generate a Voxworks API key

1. Open **Settings**, then **API Keys** in the sub-navigation.
2. Click **Generate Key** (optionally give it a **Key Name**, e.g. "Monday.com Production").
3. Click **Generate**. The key is shown once: "Copy your API key now. It won't be shown again." Copy it — Voxworks stores only a hash and never displays it again.

### Call the Create Phone Call endpoint

```bash theme={null}
curl -X POST https://api.voxworks.ai/api/v1/create-phone-call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+61291234567",
    "script_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contact": {
      "phone_number": "0429069971",
      "first_name": "John",
      "last_name": "Smith"
    },
    "objects": {
      "monday_item": {
        "item_id": "1234567890",
        "board_id": "9876543210"
      }
    }
  }'
```

| Field                                      | Required | Description                                                                                                                                                                                            |
| ------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `from_number`                              | Yes      | The Voxworks number to call from (type `string`, example `+61291234567`); must belong to your team.                                                                                                    |
| `script_id`                                | Yes      | The script to run (type `string (uuid)`).                                                                                                                                                              |
| `contact.phone_number`                     | Yes      | The person to call, any common format (type `string`, example `0429069971`), normalised to E.164.                                                                                                      |
| `contact.first_name` / `contact.last_name` | No       | Updated on an existing contact if provided.                                                                                                                                                            |
| `objects`                                  | No       | Data to attach to the contact, keyed by **Custom Variable Type** name (type `object`). Each key should match a type you've already created on the [Custom Variables](/custom-variables/overview) page. |
| `scheduled_time`                           | No       | ISO 8601 timestamp (type `string`, example `2026-02-25T09:00:00Z`); defaults to now.                                                                                                                   |

A successful call returns `201 Created` with `call_id` (type `string (uuid)`), `contact_id` (type `string (uuid)`), and `status` (type `string`, example `scheduled`).

**Store the Monday.com item ID before you send it.** To write results back to the right item later, create a Custom Variable Type (for example `monday_item`, with fields like `item_id` and `board_id`) and pass its values in `objects` on the same request, as in the example above. Once saved, the values are readable as `{{custom.monday_item.item_id}}` (type `string`, example `1234567890`) anywhere in your Voxworks flow, including in the Automation you build for the write-back below. See [linking custom variables to contacts](/custom-variables/linking-contacts) for how this data attaches to the caller's contact record.

***

## Writing call results back to Monday.com (Integration Sync)

Call results are written back using an **Automation**, not a fixed set of checkboxes. Start it from either side:

* From the script editor's **Settings** tab, the **Post-Call Automations** card ("Automations linked to this script after a call completes") lists automations tied to the script. Click **New** to create one and jump straight into its editor. If the script hasn't been saved yet, the card shows "Save the script before adding post-call automations."
* Or open **Automations** in the sidebar directly and click **New Automation**.

### Build the pipeline

1. The automation opens with the **Call Completed** trigger ("Runs after a call finishes") — pre-selected and pre-filtered to this script if you started from the Post-Call Automations card, or chosen by you in the **Create New Automation** dialog if you started from **Automations** directly. Either way, you can filter it to specific scripts or call statuses.
2. Add a **Transform** step in **Field Mapping** mode to map call and contact data onto your board's actual column IDs, one row per column — for example `call.call_summary → long_text_7`, `call.status → status_1`, `call.duration → numbers_3`, `custom.monday_item.item_id → item_id`. This is where you translate Voxworks fields into your Monday.com **column IDs** (see below) rather than column labels.
3. Add a **Destination** step, set **Destination Type** to **Integration Sync**, and pick your connected Monday.com integration.
4. Configure the request:

| Field         | Value                                                                                                                                                                               |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method        | `POST`                                                                                                                                                                              |
| Endpoint      | Any non-empty value, e.g. `/` — the connected integration's base URL already resolves to Monday.com's GraphQL API (`https://api.monday.com/v2`), so the endpoint is appended to it. |
| Headers       | Optional — add extra headers here only if Monday.com's API needs them beyond what your connected integration already supplies.                                                      |
| Body Template | The GraphQL mutation, referencing your mapped values with `{{mapped.*}}` (or `{{call.*}}` / `{{contact.*}}` / `{{custom.*}}` directly if you skipped the Transform step).           |

Example Body Template, matching the mappings above:

```json theme={null}
{
  "query": "mutation ($itemId: ID!, $columnValues: JSON!) { change_multiple_column_values(item_id: $itemId, board_id: {{custom.monday_item.board_id}}, column_values: $columnValues) { id } }",
  "variables": {
    "itemId": "{{custom.monday_item.item_id}}",
    "columnValues": "{\"long_text_7\":\"{{mapped.long_text_7}}\",\"status_1\":\"{{mapped.status_1}}\",\"numbers_3\":\"{{mapped.numbers_3}}\"}"
  }
}
```

5. Click **Test Request** to send it once with live data and confirm Monday.com accepts it (status code and response body are shown inline) before you enable the automation — if it doesn't succeed, check the response body for an authentication or validation error.
6. Save and enable the automation.

<Warning>
  There is no column picker in Voxworks — you type Monday.com's column IDs by hand into the Field Mapping target and the Body Template. A wrong or renamed column ID fails silently against Monday.com's API (visible only in the automation's **Execution Log**), not at save time in Voxworks.
</Warning>

### Finding your Monday.com column IDs

A board column's **ID** (e.g. `status_1`, `long_text_7`) is not the same as the label shown on the board, and Voxworks has no way to look it up for you. Find it on the Monday.com side — for example, by querying `boards { columns { id title } }` in Monday.com's own API playground, or via your board's column settings — then use that ID, not the display label, in your Field Mapping targets and Body Template.

***

## Managing or removing the connection

Click the gear icon on the connected Monday.com card to open **Integration Settings**, then click **Disconnect**. The **Disconnect Monday.com?** confirmation warns that disconnecting will stop all active workflows using the integration, remove access to Monday.com features from your AI agents, and delete any stored authentication tokens. You can reconnect at any time by entering an API key again.

***

## Next Steps

* [Automations](/automations/overview) — triggers, the Pipeline builder, and the full step catalogue (Source, Transform, Condition, Upsert Contact, Upsert Custom Variable, Create Call, Destination).
* [Field Mapping & Context](/automations/field-mapping) — how source paths, `mapped.*`, and `{{call.*}}` / `{{contact.*}}` / `{{custom.*}}` context values work across a pipeline.
* [Custom Variables overview](/custom-variables/overview) — creating the Custom Variable Type that carries your Monday.com item and board IDs.
* [API Reference — Authentication](/api-reference/authentication) — generating and using Voxworks API keys against the REST API.