> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.
# monday.com Integration
> Connect Gradial to monday.com to automatically ingest board items and sync results back to your boards.
**What you can do:**
* Ingest monday.com board items into Gradial with full metadata
* Trigger Gradial execution when items match your route criteria
* Write results — previews, links, updates — back to the monday.com item
* Sync files between monday.com items and Gradial
Gradial syncs monday.com on a schedule — real-time webhooks are not yet supported. New and updated items are picked up on the next sync cycle rather than instantly.
***
## Prerequisites
### Create a dedicated Gradial service user in monday.com
monday.com authors every update as the API token owner. Use a dedicated service user named **Grady** or **Gradial Bot** so customer-visible write-backs do not come from a personal employee account.
1. Create a new monday.com user with an email address dedicated to the integration (e.g., `gradial-integration@yourcompany.com`)
2. Name the user **Grady** or **Gradial Bot** — this name appears on every update Gradial posts
3. Add the service user to **every board** you plan to sync into Gradial (for private and shareable boards, the user must be invited as a subscriber)
The API token you generate must come from this dedicated service user, not a personal user. Updates, item changes, and file uploads Gradial makes in monday.com will appear as this account.
**Required token capabilities:**
| Scope | Access required |
| ----------- | -------------------------------------- |
| **Boards** | Read all target boards |
| **Items** | Read / Write (create and update items) |
| **Updates** | Write (post updates to items) |
| **Users** | Read |
| **Files** | Upload |
***
## Connect monday.com to Gradial
Go to **Integrations** in the Gradial sidebar, find monday.com under **Ticket System Integrations**, and click **Connect**. The setup wizard walks through three steps: **Connection**, **Routing**, and **Route Summary**.
### Step 1 — Generate an API token
1. Log in to monday.com **as the service user**
2. Click your profile avatar and select **Developers** to open the Developer Center
3. Go to **My Access Tokens** and click **Show** to reveal the personal API token
4. Copy the token
Treat the API token like a password. If it is ever compromised, regenerate it from the Developer Center and update the integration in Gradial.
### Step 2 — Configure the connection
On the **Connection** step of the wizard:
1. Enter an **Integration Name** to identify this connection (e.g., "My monday.com Instance")
2. Paste the service user's token into **monday.com service user API token**
3. Click **Validate Connection**
4. Once validated, click **Next** to continue to routing
Once saved, credentials are stored securely and cannot be viewed again. To update the token, delete the integration and create a new one.
### Step 3 — Configure routing
On the **Routing** step, click **Add Route** to define which monday.com items Gradial ingests and where they land in Gradial. Each route in the Route Table can be toggled on or off and configured independently.
| Field | Required | Description |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Route Name** | Required | A name to identify this route |
| **Description** | Optional | Notes about what the route is for |
| **Board ID** | Required | The numeric ID of the monday.com board to sync — found in the board URL (e.g., `yourcompany.monday.com/boards/18421333785`) |
| **Search Term** | Optional | A keyword filter — only items matching the search term are ingested |
Each route targets a single monday.com board. To sync more boards, add another route.
**Gradial Destination:**
| Field | Description |
| --------------- | ----------------------------------------------------------------- |
| **Workspace** | The Gradial workspace where ingested items will appear as threads |
| **Environment** | The Gradial environment to execute tasks in |
Click **Next** to review the **Route Summary**, and confirm the routes pull in what you expect before finishing.
For ingestion modes and best practices, see [Routing Tickets →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)
***
## How item execution works
Once a route is configured, Gradial polls monday.com for matching items and processes them automatically:
1. An item matching a route's filter criteria is discovered on the next scheduled sync
2. Gradial ingests the item as a thread, including its name, updates, column values, and files
3. The AI agent executes the requested work
4. Results — previews, links, and updates — are written back to the original monday.com item as the service user
5. Gradial continues to monitor the item for changes that trigger follow-up actions
***
## Troubleshooting
| Issue | Likely cause | Fix |
| -------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
| No items syncing | Service user missing board access | Confirm the service user is subscribed to all target boards |
| Authentication fails | Invalid or regenerated API token | Copy a fresh token from the service user's Developer Center and reconnect |
| Items appear with delay | Scheduled sync, no webhooks | Expected behavior — items sync on the next cycle, not in real time |
| Updates posted by the wrong name | Token generated from a personal account | Regenerate the token from the dedicated Grady / Gradial Bot service user |
| Files not syncing | Token lacks file upload capability | Verify the service user can upload files on the target boards |
Contact your Gradial Product Specialist or email [support@gradial.com](mailto:support@gradial.com) if issues persist.