What we do
Tools
Industries
Department
How we workLet's talk →
Home/Intercom/Intercom API
Intercom developer reference

The Intercom API: Access Tokens, Versioning, Rate Limits and Webhooks

Intercom's REST API reads and writes contacts, companies, conversations, tickets, tags and data attributes, and webhooks push events out as they happen. It reaches nearly everything. The exception is the branching logic inside Fin and Workflows, which is built in Intercom's editor. Below: what to set before your first call, how limits and webhooks behave under load, and where that edge sits.

Before your first call

Host: https://api.intercom.io for US-hosted workspaces. EU and Australian workspaces use https://api.eu.intercom.io and https://api.au.intercom.io. The wrong host returns errors for a valid token.

Auth: Authorization: Bearer {access_token}. For your own workspace, create an app and copy its token from the Developer Hub.

Developer Hub Your app Configure Authentication

Version: send an Intercom-Version header on every request. Without it you get the version set on your app, and 1.0 if none was set, which is how old integrations break on new fields.

Access token or OAuth?

Access token

Your own workspace

  • Scripts, internal syncs and private apps that only touch your company's Intercom.
  • Token comes from the app in the Developer Hub. Guard it as you would a password.
  • Tied to the teammate who installed the app or last regenerated the token. Their conversation access limits what it can see.
  • All private apps in a workspace share one rate limit.
OAuth

Other companies' workspaces

  • Public apps and integrations you sell or install for customers.
  • Each workspace admin authorizes the app and you receive a token for that workspace.
  • Never ask a customer to paste their access token into your product.
  • Each public app gets its own rate limit per workspace.

Building for your own company? An access token on a private app, installed by a long-lived admin account rather than whoever happens to be the developer. Building for many companies? OAuth from the start.

How the rate limit is really enforced

The headline is generous: 10,000 calls a minute for the private apps in a workspace (shared between them), 10,000 for each public app, and 25,000 a minute for the workspace across every app. But Intercom enforces it in 10-second windows, each allowed a sixth of the minute's total. A bulk job that fires as fast as it can hits a 429 in the first window even if its minute average is fine.

Read X-RateLimit-Remaining and X-RateLimit-Reset (a UNIX time for the end of the current window) and pace to them. Don't rely on the headers always being there: some 429 responses come without them, so fall back to a short pause and retry. List endpoints page by cursor, so store the cursor from each page and resume from it rather than restarting a long export.

Setting up a webhook that survives a bad day

Intercom's delivery rules decide how a receiver has to behave. Build to them and you won't lose events.

  1. 1

    Subscribe in the Developer Hub

    Developer Hub Your app Webhooks

    Webhook topics are only set here, not through the API. The endpoint must be HTTPS and must answer a HEAD request, which Intercom sends to check the URL. Pick the topics you need, such as new conversations, admin replies or new contacts.

  2. 2

    Verify the signature on the raw body

    Each delivery carries X-Hub-Signature: sha1=..., an HMAC-SHA1 of the raw request body keyed with your app's client_secret. Compute it before any JSON parser touches the body and compare in constant time.

    Watch for: middleware that parses and re-serializes JSON first. The bytes change and every signature fails.

  3. 3

    Return 200 within five seconds, then work

    If Intercom doesn't get a 200 within 5,000ms, it sends the notification again. Store the event, reply, and process from a queue. Slow handlers are where duplicates come from, so make processing idempotent on the notification ID.

  4. 4

    Order events yourself

    Intercom doesn't guarantee delivery order. Sort by the created_at timestamp in the payload before applying changes, or a stale update can overwrite a newer one.

  5. 5

    Watch for pauses and suspension

    Over 1,000 consecutive errors in 15 minutes pauses delivery for 15 minutes. Replying 429 throttles delivery, from a minute up to two hours, after which events are dropped. A private app returning errors for more than seven days has its subscription suspended until someone presses Set live on the Webhooks page.

    Watch for: a quiet weekend outage. Alert on your receiver's error rate, because Intercom won't tell you it has stopped sending.

Where the API stops: Fin's logic and data connectors

Fin and Intercom's Workflows are configured in visual editors: branching questions, conditions, handoff rules. The API can start and read conversations, set attributes Fin's rules use, and serve data to Fin, but it can't write or edit that branching logic. That part stays a job in the Intercom UI.

The data side is open. What used to be called Custom Actions are now data connectors (Settings, Integrations, Data connectors): calls Fin makes during a conversation to your own endpoint to fetch an order's status or an invoice, or to make a change. Most of the value in a Fin rollout sits here, because an answer from the customer's real account beats an answer from a help article. More on that on Intercom AI (Fin), and on the newer route through Intercom MCP.

Intercom API mistakes that show up a month later

The token belonged to someone who left

How you'll know: Calls start failing, or suddenly can't see some conversations, after a teammate's access changes.

Fix: Install private apps from a shared admin account and regenerate the token from there. Keep the token in a secrets store, not in a script.

No version header

How you'll know: A field you saw in the docs is missing from responses, or a payload shape changed when someone edited the app's settings.

Fix: Pin Intercom-Version on every request and upgrade on purpose, testing against the changelog for the versions in between.

Writing to an attribute that doesn't exist yet

How you'll know: Contact updates fail or drop the custom value.

Fix: Create custom data attributes first (through the data attributes endpoint or in settings), with the right type, then write to them.

Questions people ask

Does Intercom have webhooks?

Yes. You subscribe to topics in the Developer Hub (new conversations, replies, contact and ticket changes and more), and Intercom posts each event to your HTTPS endpoint, signed with X-Hub-Signature. It resends if you don't reply 200 within five seconds.

Does Intercom have an official SDK?

Yes. Intercom publishes client libraries for several languages, including JavaScript and Ruby, which take your access token and set the header for you. There are also mobile SDKs for putting the Messenger in iOS and Android apps, which are a separate thing from the REST API.

Can I use the API to change what Fin AI says or how it behaves?

Partly. You can give Fin live data through data connectors, change the attributes its rules check, and update the help articles it answers from. You can't build or edit Fin's branching logic or Workflows through the API; that's done in Intercom's editor.

What are Intercom rate limits like?

10,000 calls a minute for private apps in a workspace (shared), 10,000 per public app, and 25,000 a minute across a workspace, enforced in 10-second windows of a sixth each. Over the limit returns a 429 with rate_limit_exceeded. Bulk syncs are what hit it.

Can the Intercom API export all my data?

Mostly, yes. Contacts, companies, conversations and tickets can all be listed and pulled through the API, page by page, which is the usual basis for a backup, a warehouse feed or a migration. Plan the export around the 10-second rate windows so it doesn't stall.

Which Intercom API version should I use?

Pin one explicitly with the Intercom-Version header, usually the newest stable version when you start. If you leave it off, requests use the version set on your app, or 1.0 if none was set, and responses won't match current docs.

Who builds Intercom API integrations for SaaS companies?

That's the work n-frames takes on: billing and product-data syncs, webhook receivers built to Intercom's delivery rules, and Fin data connectors that read and act on the customer's real account, then keeps them running as Intercom versions change.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.