monday.com API Integration Guide

monday.com’s API is GraphQL end to end, one endpoint, and the query itself decides what comes back, which trips up anyone arriving with REST habits. The real early decisions are less about syntax and more about scope: a personal token scoped to one user’s own account, or a registered OAuth app meant to be installed into accounts you don’t own; a rate-limit model built on query complexity rather than a flat request count; and a versioning system that ages your integration by date rather than a version number bump you control. This guide walks through all of that, plus board-level webhooks and their challenge-handshake step, the apps marketplace, and where a direct API build earns its cost over a no-code connector. If you’re weighing whether to build this in-house or bring in help, monday.com CRM implementation services covers what a properly scoped build actually involves beyond the API layer.

Which auth method do you actually need: personal token or OAuth app?

The first question isn’t “token or OAuth,” it’s “whose account is this running against.” A personal API token authenticates as a specific user and inherits exactly what that user can already see in the UI — no consent screen, no expiry to manage, generated directly from your profile’s Developer settings. An OAuth app is what you register when other businesses, accounts you don’t control, need to install your integration and grant it access through a consent flow.

monday.com’s own developer documentation frames personal tokens as tied to “the user making the call,” which is the detail most tutorials gloss over. It’s not a service-account credential; it’s that person’s credential, with that person’s permissions, full stop. That has a direct operational consequence: if the person whose token an integration runs on changes roles, loses board access, or leaves the company, the integration silently loses access too, sometimes to boards nobody remembers it depended on.

If you’re syncing your own agency’s or one client’s boards into a warehouse or another internal tool, a personal token is the right starting point — it’s issued in seconds from your profile’s Developer settings, per monday’s authentication documentation, and doesn’t require standing up a redirect URI or handling any refresh cycle. If you’re building something meant to be installed by other monday.com customers, you register an app in the Developer Center instead, which hands you a client_id and client_secret and requires you to declare which of monday’s 21 granular permission scopes (things like boards:read, boards:write, webhooks:write) your app actually needs.

One detail worth flagging before you commit code to either path: monday.com currently has two live OAuth flows, and they behave differently enough that it matters which one a given app was registered under. The legacy OAuth 2.0 flow issues access tokens that never expire and has no refresh-token support at all — the token is valid until the user uninstalls the app, full stop. The newer OAuth 2.1 flow, described on monday’s OAuth reference, adds expiring access tokens, refresh tokens, and revocation, which is the more defensible security posture for anything shipping in 2026. Check which flow an app is actually registered under before writing token-refresh logic that the legacy flow doesn’t support and doesn’t need.

How do monday.com’s rate limits actually work?

monday.com doesn’t cap you at a flat number of requests per minute the way many REST APIs do — it caps you by query complexity, a points-based cost that scales with how much data and how many nested fields a single GraphQL query or mutation touches. A short query asking for ten items’ names costs far less than a query pulling those same ten items with all their column values, connected boards, and update history nested inside.

Per monday’s official rate-limits documentation, a personal API token gets a combined budget of 10 million complexity points per minute for reads and writes together (1 million on trial, free, and NGO accounts), while an OAuth app token gets 5 million points per minute for reads and 5 million for writes, tracked as two separate budgets rather than one shared pool. On top of the complexity budget, request-count and concurrency limits vary by the account’s plan tier: Enterprise accounts get 5,000 queries per minute and 250 concurrent requests, Pro gets 2,500 queries per minute and 100 concurrent, and other tiers are capped at 1,000 queries per minute and 40 concurrent. Every rate-limit error response includes a retry_in_seconds field telling you exactly how long to wait before trying again, so there’s no need to guess at a backoff interval.

The practical takeaway is that a large historical sync needs to be planned against complexity, not against a request-count guess. Pulling every column value, every connected board, and every update on a few thousand items in one query can burn a meaningful chunk of a minute’s budget in a single call, even though it’s technically “one request.” Ask for only the fields you need in each query rather than defaulting to a broad field set, paginate large board reads instead of requesting everything at once, and if you’re building an OAuth app, remember that read-heavy and write-heavy work draw from separate pools — a backfill that’s almost entirely reads won’t touch your write budget at all, which is useful to know before over-engineering a shared rate limiter that treats them as one number.

How does monday.com’s API versioning work, and why does that matter for a real build?

monday.com versions its API by release date rather than by an incrementing number — a version is named something like 2026-07, representing the year and month it became the default. Per monday’s API versioning documentation, three versions run in parallel at any given time: a Release Candidate for unstable preview features, the Current stable default, and an older Maintenance version kept around for integrations mid-migration. A new version ships quarterly, and monday guarantees the Current version stays stable, no breaking changes, for at least six months before it ages into Maintenance and eventually gets deprecated, with deprecation announced at least six months in advance.

The operational implication is straightforward: pin your version explicitly with the API-Version request header rather than letting requests default to whatever’s Current, since Current is a moving target on a quarterly clock. An integration that never sets API-Version will keep working across most quarterly bumps, but a genuinely breaking field or behavior change in a new Current version will hit it without warning, whereas an explicitly pinned integration ages into Maintenance predictably and gives you a real deadline to plan a migration against instead of an unannounced surprise in production.

What does the GraphQL API surface actually cover?

The API works with the same primitives you see in the UI: boards, groups, items, subitems, and column values, plus users, workspaces, updates, and docs. Per monday’s GraphQL overview, the API currently supports monday’s work management, CRM (monday sales CRM), dev, and service products, but does not yet cover Workforms. Every request, whether it’s a query (read) or a mutation (write), goes to https://api.monday.com/v2 as a POST, and you shape the response by specifying exactly which fields you want, nested as deep as the schema allows.

A basic item-creation mutation looks like this:

mutation {
  create_item (
    board_id: 1234567890,
    item_name: "New lead: Acme Corp",
    column_values: "{\"status\": {\"label\": \"New\"}, \"text\": \"Inbound form submission\"}"
  ) {
    id
    name
  }
}

That one call creates an item and sets two column values in a single round trip, which is the general GraphQL advantage over a REST API’s separate create-then-update calls — fewer requests for the same amount of work, which also means less complexity budget spent per outcome. Reading data back works the same way: a boards query with nested items_page and column_values fields returns exactly the shape you ask for, nothing more, so a lean query genuinely costs less complexity than a greedy one pulling every field on every item.

Pagination matters more on monday’s API than it does on a lot of REST equivalents, because a board can hold thousands of items and a single query has a documented cap of 100 items per page. The items_page field returns a cursor string alongside the items themselves, and passing that cursor into the next next_items_page query walks the rest of the board without re-fetching anything already retrieved. Skipping cursor-based pagination in favor of repeated full-board queries is a quiet way to both waste complexity budget and risk missing items on a board that’s actively changing while your sync runs, since a naive re-query doesn’t guarantee stable ordering the way a cursor-based walk does. Column values deserve a specific mention too: each column type (status, date, people, numbers, dropdown, connect-boards) serializes to and from a slightly different JSON shape inside column_values, and the shape for a status column isn’t the shape for a people column — worth checking monday’s column-type reference for the exact structure before assuming one format works everywhere.

How do webhooks work on monday.com?

monday.com actually has two distinct webhook systems, and mixing them up is a common source of confusion in third-party tutorials. Board-level webhooks fire on data events, an item created, a status column changed, an item moved to a group, and are set up per board through a create_webhook GraphQL mutation, per monday’s webhooks API reference:

mutation {
  create_webhook (
    board_id: 1234567890,
    url: "https://your-endpoint.example.com/webhook",
    event: change_status_column_value
  ) {
    id
    board_id
  }
}

Before that subscription activates, monday.com sends a one-time verification POST to your URL containing a randomly generated challenge token, and your endpoint has to echo the exact same JSON body straight back to prove you control that URL. Skip that handshake and the webhook never goes live — it’s a small step, but it’s exactly the kind of detail a copied code snippet omits if it wasn’t built against the real flow. Supported board-level events cover item lifecycle (create_item, item_archived, item_deleted, item_moved_to_any_group), column changes (change_column_value, change_status_column_value, change_specific_column_value), subitem events, and update events, giving you fairly granular control over what actually triggers your endpoint instead of one firehose event for every board change.

App lifecycle webhooks are a separate system entirely, covering install, uninstall, and subscription events (trial started, subscription renewed, cancellation) for apps published through the Developer Center, and they arrive signed with a JWT in the Authorization header rather than the challenge-handshake pattern board-level webhooks use. If your integration only cares about data changing on a board, you want board-level webhooks; if you’re building a marketplace app and need to know when someone installs or cancels it, that’s the app lifecycle system, and treating the two as interchangeable is a fast way to build a listener that never fires.

What’s the apps marketplace, and when do you actually need it?

The monday apps framework lets you build board views, dashboard widgets, automations, and integrations as installable features rather than one-off API scripts, and monday code is the platform’s own hosting layer for those apps — app hosting, a CLI, SDKs, and the GraphQL API in one toolchain, per monday’s SDK documentation. Publishing to the monday marketplace puts an app in front of monday’s own reported customer base of over 245,000 accounts, but that reach only matters if you’re building something meant to be discovered and installed broadly, rather than a purpose-built internal integration for one team or client.

For most agencies and internal teams, the marketplace and the full apps framework are more than the job calls for. A straight personal-token integration or a narrowly scoped OAuth app for a handful of client accounts covers the common case, sales-to-delivery handoffs, a data warehouse sync, a billing reconciliation, without the overhead of app review and marketplace listing requirements. Reach for the full apps framework specifically when the plan is a genuinely distributable product other monday.com customers install themselves, not as a default starting point for internal tooling.

Even short of a marketplace listing, the apps framework has a private-app middle ground worth knowing about — you can build a board view, dashboard widget, or automation using the same SDK and host it on monday code without ever submitting it for public review. That’s a reasonable path when a client wants a custom UI element embedded directly inside their monday.com workspace (a rendered chart on a board, a custom action button) rather than a background integration running outside the platform, and it avoids standing up separate hosting infrastructure for something that only that one account will ever use.

When is the direct API worth it over Zapier or Make?

No-code connectors and direct API work aren’t strictly either/or, and plenty of teams run both at once. Zapier and Make tend to be the better fit for wiring a handful of external apps together quickly, for automations a non-developer needs to read and maintain, and for lower request volume where complexity budgeting and custom retry logic aren’t a real concern. If that describes your situation more than a custom build does, for automation work generally, autoesta’s Zapier and Make automation team builds exactly that kind of no-code connection between a platform like monday.com and the rest of a client’s stack without custom API code.

Direct API and webhook work earns its added complexity at sustained request volume, when a query needs a shape a no-code connector’s pre-built triggers and actions can’t express, or when you’re building something meant to run across many accounts rather than one workspace wired to one other tool. Custom GraphQL queries that pull deeply nested column data in a single call, and precise board-level webhook events instead of a connector’s coarser polling interval, are the two places the raw API tends to pull ahead of a no-code equivalent most clearly. There’s no single published breakeven point between the two approaches in cost or volume; treat the decision as shaped by your integration’s actual requirements rather than a universal threshold, because monday.com hasn’t published one and neither has anyone else credibly.

A few integration patterns worth knowing

Three shapes come up often enough in monday.com integration work to name directly, presented as illustrative patterns rather than case studies.

A data warehouse sync pulls items, column values, and update history, via scheduled GraphQL queries or board-level webhooks, into a reporting tool that monday’s native dashboards don’t cover, cross-account rollups or historical trend analysis that spans more history than a live dashboard widget is built for. The scheduled-pull portion is where complexity budgeting matters most, since a broad historical query on a large board can consume a meaningful share of a minute’s points in one call, while the webhook portion barely touches the budget since inbound event payloads don’t cost complexity the way outbound queries do.

A sales-to-delivery handoff connects a monday sales CRM board to project or onboarding boards, so a deal moving to “Closed Won” fires a board-level webhook that creates the corresponding delivery item automatically, instead of someone re-typing the account into a separate board. The reconciliation question worth deciding up front is which board is authoritative for a given field once both exist, so an automation loop doesn’t end up processing its own write as an incoming trigger.

External system sync uses create_item and change_column_value mutations alongside board-level webhooks to keep a monday.com board aligned with an external billing or support system. As with any two-way sync, the trickiest part is rarely the API calls themselves, it’s deciding explicitly which system wins when the same record changes in both places close together in time, and building that rule before the first production sync runs rather than discovering the gap after a support ticket flags a silently overwritten field.

All three patterns share a failure mode worth planning around up front: an integration that writes to monday.com through the API and also listens for board-level webhooks on the same data can end up processing its own write as an incoming event, the same loop risk that shows up on any platform with both a writable API and outbound webhooks. Tagging API-originated writes with an identifiable value in an otherwise-unused column, or checking a triggerTime window against your own last-write timestamp, is a simple enough guard that avoids the loop without adding a separate message queue just to de-duplicate events.

Getting started without the common mistakes

Most friction in a new monday.com integration traces back to a small set of avoidable decisions: building on a single person’s personal token for something that needs to survive a role change, picking OAuth when a personal token would have done the job, not budgeting complexity points before a large backfill, or skipping the webhook challenge handshake and wondering why a subscription never activates. None of these need deep platform expertise to avoid — deciding on auth model and query cost before writing the first mutation is what actually prevents them.

Not every team needs custom API code to get real value out of monday.com either. If the underlying goal is board automation and workflow structure inside monday.com rather than a standalone integration product, that’s platform configuration work rather than an API build, and it’s worth scoping separately from custom development. On the automation side more broadly, for teams whose stack centers on GoHighLevel rather than monday.com, HighLevel Automation Team builds workflow automation directly on that platform, a useful reference point for what platform-native automation work looks like versus a custom API integration, even outside the monday.com context specifically. Before committing to either path on monday.com, monday.com CRM automation recipes covers what’s achievable with native automations before a custom API build becomes necessary, and monday.com CRM implementation cost breaks down what agencies typically charge for the two kinds of work.

If you’re scoping a monday.com integration and want a second read on the auth model or data architecture before you build, aibrevo’s monday.com implementation team works with the GraphQL API and board architecture day to day and can sanity-check an approach before it turns into a rebuild.