A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Intercom API is how an app or AI agent works with an Intercom workspace: reading and replying to conversations, creating and updating contacts, managing support tickets, publishing help center articles, and recording the events a customer triggers. Access is granted through an access token, and the OAuth scopes on that token set which data a call can read or change. A workspace lives in a single region with its own data residency, and a state change can fire a webhook to a registered endpoint.
How an app or AI agent connects to Intercom determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Intercom tools to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a cursor, at https://api.intercom.io. A workspace is hosted in one region, and the request can be sent to the regional base, https://api.eu.intercom.io for the EU or https://api.au.intercom.io for Australia, or to api.intercom.io which routes to the workspace's region. A call authenticates with an access token in the Authorization header and pins an API version with the Intercom-Version header.
Intercom POSTs a notification to an HTTPS endpoint when a subscribed topic fires, like conversation.user.created or ticket.state.updated. Each topic maps to an OAuth scope, so an app only receives topics its token is allowed to read. The receiver verifies the X-Hub-Signature header against the app's client secret to confirm the request came from Intercom.
A hosted Model Context Protocol server at https://mcp.intercom.com/mcp exposes Intercom tools to AI agents and LLM clients, with a deprecated SSE endpoint at https://mcp.intercom.com/sse. It authenticates with OAuth or a Bearer access token and provides 13 tools: a universal search and fetch, plus search_conversations, get_conversation, search_contacts, get_contact, list_companies, get_company, list_articles, search_articles, get_article, create_article, and update_article. It is currently supported only for US-hosted workspaces.
A private app gets a long-lived access token from the Developer Hub that calls only its own workspace. The token is sent as Authorization: Bearer. It carries the scopes selected for the app, and stays valid until it is revoked. This is the route for an integration acting on a single, known workspace.
A public app uses the OAuth 2.0 authorization-code flow so a customer can connect their own Intercom workspace without sharing a token. The app requests only the scopes it needs, and the resulting access token is sent the same way, as Authorization: Bearer. Intercom's OAuth does not issue refresh tokens, so a token stays valid until the user revokes access or the app deauthorizes.
The Intercom API is split into areas an agent can act on, like contacts, conversations, companies, tickets, articles, and events. Each area has its own methods and its own permission scope, and some grant access to far more than others.
Create, retrieve, update, delete, list, and search contacts (users and leads), and archive or unarchive them.
Create, retrieve, list, and search conversations, reply to them, and close, snooze, open, or assign them.
Send an admin-initiated message to a contact, as an in-app message or an email.
Create, retrieve, and update tickets, and reply to them.
Create or update a company, retrieve one, and list companies in a workspace.
Create, retrieve, update, delete, list, and search help center articles.
Submit a data event for a contact and list a contact's recent events.
List admins, retrieve one, identify the current admin, and set an admin's away status.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ContactsCreate, retrieve, update, delete, list, and search contacts (users and leads), and archive or unarchive them.7 | ||||||
| POST | /contacts | Create a contact, either a user (an identified person) or a lead (an anonymous one). | write | Write users | Current | |
Granted by the 'Write users and companies' scope. Acts oncontact Permission (capability) Write usersVersionAvailable since the API’s base version Webhook event contact.user.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /contacts/{id} | Retrieve a single contact by its Intercom id. | read | Read one user | Current | |
Covered by 'Read one user and one company' or the broader 'Read and list users and companies'. Acts oncontact Permission (capability) Read one userVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /contacts/{id} | Update a contact's attributes by its Intercom id. | write | Write users | Current | |
Granted by the 'Write users and companies' scope. Acts oncontact Permission (capability) Write usersVersionAvailable since the API’s base version Webhook event contact.user.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /contacts/{id} | Delete a single contact by its Intercom id. | write | Write users | Current | |
Granted by the 'Write users and companies' scope. Acts oncontact Permission (capability) Write usersVersionAvailable since the API’s base version Webhook event contact.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /contacts | List all contacts in the workspace, cursor-paginated. | read | Read users | Current | |
Covered by 'Read and list users and companies'. Acts oncontact Permission (capability) Read usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts/search | Search contacts with a query of filters over standard and custom attributes. | read | Read users | Current | |
A search, sent as a POST with a query body; covered by 'Read and list users and companies'. Acts oncontact Permission (capability) Read usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /contacts/{id}/archive | Archive a single contact, removing them from active lists. | write | Write users | Current | |
Granted by the 'Write users and companies' scope. Acts oncontact Permission (capability) Write usersVersionAvailable since the API’s base version Webhook event contact.archivedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConversationsCreate, retrieve, list, and search conversations, reply to them, and close, snooze, open, or assign them.6 | ||||||
| POST | /conversations | Create a conversation initiated by a contact (a message from a user or lead). | write | Write conversations | Current | |
Creating a contact-initiated conversation; the 'Write conversations' scope. Acts onconversation Permission (capability) Write conversationsVersionAvailable since the API’s base version Webhook event conversation.user.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /conversations/{id} | Retrieve a single conversation, including its parts (the messages and notes within it). | read | Read conversations | Current | |
Read-only; the 'Read conversations' scope. Acts onconversation Permission (capability) Read conversationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /conversations | List all conversations in the workspace, cursor-paginated. | read | Read conversations | Current | |
Read-only; the 'Read conversations' scope. Acts onconversation Permission (capability) Read conversationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /conversations/search | Search conversations with a query of filters over their attributes. | read | Read conversations | Current | |
A search, sent as a POST with a query body; the 'Read conversations' scope. Acts onconversation Permission (capability) Read conversationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /conversations/{id}/reply | Reply to a conversation as an admin or on behalf of a contact, or add a note. | write | Write conversations | Current | |
Granted by 'Write conversations' ('Reply to, mark as read and close conversations'). Acts onconversation Permission (capability) Write conversationsVersionAvailable since the API’s base version Webhook event conversation.admin.repliedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /conversations/{id}/parts | Manage a conversation by adding a part: close, snooze, open, or assign it to an admin or team. | write | Write conversations | Current | |
The message_type in the body selects the action (close, snoozed, open, assignment); the 'Write conversations' scope. Acts onconversation Permission (capability) Write conversationsVersionAvailable since the API’s base version Webhook event conversation.admin.closedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MessagesSend an admin-initiated message to a contact, as an in-app message or an email.1 | ||||||
| POST | /messages | Send an admin-initiated message to a contact, as an in-app message or an email. | write | Write conversations | Current | |
message_type is in_app or email; sending starts a new conversation, governed by the 'Write conversations' scope. Acts onmessage Permission (capability) Write conversationsVersionAvailable since the API’s base version Webhook event conversation.admin.single.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TicketsCreate, retrieve, and update tickets, and reply to them.4 | ||||||
| POST | /tickets | Create a ticket of a given ticket type for a contact. | write | Write tickets | Current | |
The 'Write tickets' scope ('Create tickets'). Acts onticket Permission (capability) Write ticketsVersionAvailable since the API’s base version Webhook event ticket.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /tickets/{id} | Retrieve a single ticket by its id. | read | Read tickets | Current | |
Read-only; the 'Read tickets' scope ('View tickets'). Acts onticket Permission (capability) Read ticketsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /tickets/{id} | Update a ticket's state, attributes, or assignment. | write | Write tickets | Current | |
The 'Write tickets' scope. Acts onticket Permission (capability) Write ticketsVersionAvailable since the API’s base version Webhook event ticket.state.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /tickets/{id}/reply | Reply to a ticket as an admin or on behalf of a contact, or add a note. | write | Write tickets | Current | |
The 'Write tickets' scope. Acts onticket Permission (capability) Write ticketsVersionAvailable since the API’s base version Webhook event ticket.admin.repliedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CompaniesCreate or update a company, retrieve one, and list companies in a workspace.3 | ||||||
| POST | /companies | Create or update a company; Intercom looks it up by company_id and updates it if found, or creates it if not. | write | Write companies | Current | |
An upsert by company_id; granted by 'Write users and companies'. Acts oncompany Permission (capability) Write companiesVersionAvailable since the API’s base version Webhook event company.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /companies/{id} | Retrieve a single company by its Intercom id. | read | Read one company | Current | |
Covered by 'Read one user and one company' or the broader 'Read and list users and companies'. Acts oncompany Permission (capability) Read one companyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /companies | List companies in the workspace, optionally filtered by name, company_id, tag, or segment. | read | Read companies | Current | |
Covered by 'Read and list users and companies'. Acts oncompany Permission (capability) Read companiesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ArticlesCreate, retrieve, update, delete, list, and search help center articles.4 | ||||||
| POST | /articles | Create a help center article. | write | Write articles | Current | |
The 'Read and Write articles' scope. Acts onarticle Permission (capability) Write articlesVersionAvailable since the API’s base version Webhook event article.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /articles/{id} | Retrieve a single help center article by its id. | read | Read articles | Current | |
Read-only; the 'Read and list articles' scope. Acts onarticle Permission (capability) Read articlesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /articles/{id} | Update a help center article by its id. | write | Write articles | Current | |
The 'Read and Write articles' scope. Acts onarticle Permission (capability) Write articlesVersionAvailable since the API’s base version Webhook event article.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /articles/search | Search help center articles by phrase, state, and help center. | read | Read articles | Current | |
Read-only; the 'Read and list articles' scope. Acts onarticle Permission (capability) Read articlesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data eventsSubmit a data event for a contact and list a contact's recent events.2 | ||||||
| POST | /events | Submit a data event for a contact, recording an action they took. Returns 202 Accepted with an empty body. | write | Write events | Current | |
The 'Write events' scope ('Ability to submit events'). Acts onevent Permission (capability) Write eventsVersionAvailable since the API’s base version Webhook event event.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /events | List a contact's data events, identified by user_id, email, or intercom_user_id. Only events less than 90 days old are listable. | read | Read events | Current | |
Read-only; the 'Read events' scope ('List all events belonging to a user'). Acts onevent Permission (capability) Read eventsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AdminsList admins, retrieve one, identify the current admin, and set an admin's away status.3 | ||||||
| GET | /admins | List all admins (teammates) in the workspace. | read | Read admins | Current | |
Read-only; the 'Read admins' scope. Acts onadmin Permission (capability) Read adminsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me | Identify the current admin, the teammate the access token authenticates as. | read | Read admins | Current | |
Returns the admin and workspace tied to the token; covered by the 'Read admins' scope. Acts onadmin Permission (capability) Read adminsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /admins/{id}/away | Set an admin's away status and whether new conversations should be reassigned while away. | write | Update admins | Current | |
The 'Update admins' scope ('Update away mode for admins'). Acts onadmin Permission (capability) Update adminsVersionAvailable since the API’s base version Webhook event admin.away_mode_updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Intercom can notify an app when something happens in a workspace, like a contact starting a conversation or a ticket changing state. It sends a notification with the topic and the affected object, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
contact.user.created | A user (an identified contact) was created in the workspace. | /contacts |
contact.user.updated | A user's attributes changed. | /contacts/{id} |
contact.archived | A contact was archived and removed from active lists. | /contacts/{id}/archive |
contact.deleted | A contact was permanently deleted. | /contacts/{id} |
conversation.user.created | A contact started a new conversation. | /conversations |
conversation.admin.replied | An admin replied to a conversation. | /conversations/{id}/reply |
conversation.admin.closed | An admin closed a conversation. | /conversations/{id}/parts |
conversation.admin.single.created | An admin started a direct, admin-initiated message to a contact. | /messages |
ticket.created | A ticket was created. | /tickets |
ticket.state.updated | A ticket's state changed. | /tickets/{id} |
ticket.admin.replied | An admin replied to a ticket. | /tickets/{id}/reply |
company.created | A company was created in the workspace. | /companies |
article.created | A help center article was created. | /articles |
article.updated | A help center article was updated. | /articles/{id} |
event.created | A data event was recorded for a contact. | /events |
admin.away_mode_updated | An admin's away mode was changed. | /admins/{id}/away |
Intercom limits how fast an app can call, by a per-app and per-workspace ceiling measured per minute but enforced in ten-second windows.
Intercom meters requests by a per-app and per-workspace ceiling, not by a per-method cost. A private app defaults to 10,000 API calls per minute per app and 25,000 per minute per workspace, where multiple private apps in a workspace share the workspace total; a public app gets its own 10,000 per minute that does not count against other apps. The per-minute allowance is enforced in ten-second windows, so a 1,000-per-minute limit permits about 166 calls per ten seconds. A successful response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, and going over returns HTTP 429.
List endpoints are cursor-based: a response includes a pages object with a next cursor, passed as starting_after on the following request, until no further cursor is returned. Search endpoints (a POST with a query body) page the same way through a pagination object. Page size is set with per_page, up to a maximum of 150.
A list or search page returns at most 150 records, the maximum value of per_page. Data events are listable only while less than 90 days old. A submitted data event returns 202 Accepted with an empty body.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request / parameter_invalid | A general client error, often malformed data or a missing or invalid parameter. | Read the error message, fix the request body or parameters, and resend. |
| 401 | unauthorized / token_unauthorized | No valid access token was provided, or the token lacks the scope the endpoint needs. | Send a valid Bearer token, and confirm the app has the OAuth scope the method requires. |
| 403 | forbidden | The request is not allowed for this token, even though it authenticated. | Check the app's permissions and the workspace it is acting on. |
| 404 | not_found | The resource was not found, or is in a different region than the one called. | Verify the id, and confirm the request is hitting the workspace's hosting region. |
| 422 | unprocessable_entity | The data was well-formed but semantically invalid, for example a value that fails validation. | Correct the invalid field named in the error and resend. |
| 429 | rate_limit_exceeded | The app or workspace reached its rate limit. The X-RateLimit-Remaining and X-RateLimit-Reset headers show how many calls are left and when the window resets. | Back off until the reset time, then retry, and smooth the request rate across the ten-second windows. |
| 500 | server_error | An error on Intercom's side, which can also appear as 502, 503, or 504. | Retry with backoff, and contact Intercom support if it persists. |
Intercom versions its API with a dotted number, like 2.15, sent in the Intercom-Version header, and pins a default version to each app. Breaking changes ship only in a new version, so a pinned integration keeps working until it chooses to move up.
The current default API version. Intercom versions with a dotted number sent in the Intercom-Version header and pins a default to each app; breaking changes ship only in a new version.
A version that introduced new capabilities across calls, tickets, and messaging.
A dated API version in the supported set, pinned with the Intercom-Version header.
An earlier dated API version.
An earlier dated API version.
Pin a version on the app and move up on a schedule that suits the integration.
Intercom API changelog ↗Bollard AI sits between a team's AI agents and Intercom. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.