# Monday.com

SureCloud connects to Monday.com to retrieve board items, column values, and workspace membership data. This allows SureCloud to track the status of compliance tasks, remediation action items, and audit deliverables managed on Monday.com boards — confirming that work is progressing and that ownership and due dates are assigned.

## Authentication and setup

Monday.com uses OAuth 2.0 for third-party app integrations. SureCloud connects via the Monday.com OAuth flow.

{% hint style="info" %}
SureCloud uses OAuth 2.0 for this integration. No credentials are stored — access is maintained via a refresh token that SureCloud rotates automatically.
{% endhint %}

{% stepper %}
{% step %}

### Initiate the connection in SureCloud

Navigate to **SureCloud → Integrations → Monday.com → Connect** and click **Authorise with Monday.com**. SureCloud will redirect you to the Monday.com authorisation page.
{% endstep %}

{% step %}

### Approve the connection

Log in to Monday.com with an account that has access to the relevant boards. Select the workspace to connect and approve the requested scopes. Click **Allow**.
{% endstep %}

{% step %}

### Return to SureCloud

After authorisation, you will be redirected back to SureCloud with the integration status updated to **Connected**. Click **Test Connection** to confirm data is accessible.
{% endstep %}
{% endstepper %}

## Endpoints

Monday.com exposes its data via a single GraphQL endpoint at `https://api.monday.com/v2`. SureCloud uses the following queries:

| API Call                         | Use Case                                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------------------ |
| `POST /v2` — `boards` query      | Enumerate boards to identify compliance and remediation workspaces                         |
| `POST /v2` — `items_page` query  | Retrieve items (tasks) on a board with column values including status, owner, and due date |
| `POST /v2` — `items_by_id` query | Retrieve individual item detail for specific task evidence                                 |
| `POST /v2` — `users` query       | Enumerate workspace members and their roles                                                |
| `POST /v2` — `workspaces` query  | List workspaces to confirm organisational scope                                            |

## Pagination

`items_page` uses cursor-based pagination. SureCloud uses the `cursor` value returned in each response as the cursor in the next request, continuing until no cursor is returned.

```json
POST /v2
{
  "query": "query { boards(ids: [12345]) { items_page(limit: 500, cursor: \"<value_from_previous_response>\") { cursor items { id name column_values { id value } } } } }"
}
```

`boards` and `users` queries use limit/page pagination with an incrementing `page` parameter.

## Required permissions / scopes

SureCloud requests the following OAuth scopes from Monday.com:

| Scope             | Purpose                            |
| ----------------- | ---------------------------------- |
| `boards:read`     | Read board structure and item data |
| `users:read`      | Enumerate workspace members        |
| `workspaces:read` | Access workspace metadata          |

No write permissions are requested.

## Polling frequency

| Data Type                              | Interval       |
| -------------------------------------- | -------------- |
| Board items and status column values   | Every 6 hours  |
| Board structure and column definitions | Every 24 hours |
| Workspace members                      | Every 24 hours |

## Troubleshooting

<details>

<summary>OAuth authorisation fails or returns a scope error</summary>

Ensure the account used for authorisation has Admin or Member-level access to the Monday.com account (not just guest access). Guest accounts may not be able to authorise OAuth applications. Retry from **SureCloud → Integrations → Monday.com → Connect** with a full member account.

</details>

<details>

<summary>Boards are missing from SureCloud's data collection</summary>

SureCloud can only access boards that the authorising account is a member of. Private boards require explicit membership. Add the authorising account to any relevant private boards in Monday.com and trigger a manual refresh in SureCloud.

</details>

<details>

<summary>Item status values appear as raw JSON rather than readable labels</summary>

Monday.com column values are returned as JSON objects containing both the label and index. SureCloud parses the `label` field from status column values to present human-readable status names. If labels are displaying unexpectedly, the board's status column may have been modified after the initial connection. Trigger a manual refresh to re-fetch column definitions.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/monday.com.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.