Intercom integration: operations for AI agents
Intercom connects to Type.com as an integration. This page lists the 259 operations documented for Claude and Codex in Type.com: 127 read, 63 write, 69 destructive.
About Intercom
Intercom provides live chat, messaging, and customer engagement tools, enabling businesses to drive conversions, handle support, and personalize communication at scale
Categories: Customer Support
How to connect Intercom to Type.com
- Connect
- Managed OAuth through Pipedream when enabled for your workspace; Access token
- Access
- Organization connection: one shared account for the workspace.
To add the connection, follow the steps in Space connections.
Documented operations
259 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.
259 operations listed.
Admins
- Read
Identify an admin
You can view the currently authorised admin along with the embedded app object (a "workspace" in legacy terminology). 🚧 Single Sign On If you are building a custom "Log in with Intercom" flow for your site, and you call the /me endpoint to identify the logged-in user, you should not accept any sign-ins from users with unverified email addresses as it poses a potential impersonation security risk.
GET /me - Read
List all activity logs
You can get a log of activities by all admins in an app.
GET /admins/activity_logs - Read
Search activity logs
Search and filter admin activity logs using a POST request with event type filter in the request body. You can find more details about the available event types in the List all activity log event types endpoint.
POST /admins/activity_logs/search - Read
List all activity log event types
You can get a list of all activity log event types. This is useful for discovering valid values to use with the eventtypes filter on the List all activity logs endpoint.
GET /admins/activity_log_event_types - Read
List all admins
You can fetch a list of admins for a given workspace.
GET /admins - Read
Retrieve an admin
You can retrieve the details of a single admin.
GET /admins/{admin_id} - Destructive
Set an admin to away
You can set an Admin as away for the Inbox.
PUT /admins/{admin_id}/away
Macros
- Read
Retrieve a macro
You can fetch a single macro (saved reply) by its ID. The macro will only be returned if it is visible to the authenticated user based on its visibility settings. Visibility Rules A macro is returned based on its visibleto setting: - everyone: Always visible to all team members - specificteams: Only visible if the authenticated user belongs to one of the teams specified in visibletoteamids If a macro exists but is not visible to the authenticated user, a 404 error is returned. Placeholder Transformation The API transforms Intercom placeholders to a more standard XML-like format in the body field: - From: {{user.name | fallback: 'there'}} - To: Default values in placeholders are HTML-escaped for security.
GET /macros/{id} - Read
List all macros
You can fetch a list of all macros (saved replies) in your workspace for use in automating responses. The macros are returned in descending order by updatedat. Pagination This endpoint uses cursor-based pagination via the startingafter parameter. The cursor is a Base64-encoded JSON array containing [updatedat, id] of the last item from the previous page. Placeholder Transformation The API transforms Intercom placeholders to a more standard XML-like format: - From: {{user.name | fallback: 'there'}} - To:
GET /macros
Office Hours
- Read
Retrieve an office hours exception
You can fetch the details of a single office hours exception.
GET /office_hours_schedules/{office_hours_schedule_id}/office_hours_exceptions/{id} - Read
List all office hours exceptions
You can fetch a list of all exceptions for an office hours schedule.
GET /office_hours_schedules/{office_hours_schedule_id}/office_hours_exceptions - Read
Retrieve an office hours schedule
You can fetch the details of a single office hours schedule.
GET /office_hours_schedules/{id} - Read
List all office hours schedules
You can fetch a list of all office hours schedules for the workspace.
GET /office_hours_schedules - Write
Create an office hours exception
You can create an exception for an office hours schedule. Use closed to mark the day closed (omit timeintervals) or customhours to supply replacement intervals.
POST /office_hours_schedules/{office_hours_schedule_id}/office_hours_exceptions - Write
Create an office hours schedule
You can create a new office hours schedule for the workspace.
POST /office_hours_schedules - Destructive
Update an office hours exception
You can update an existing office hours exception.
PUT /office_hours_schedules/{office_hours_schedule_id}/office_hours_exceptions/{id} - Destructive
Delete an office hours exception
You can delete a single office hours exception.
DELETE /office_hours_schedules/{office_hours_schedule_id}/office_hours_exceptions/{id} - Destructive
Update an office hours schedule
You can update an existing office hours schedule.
PUT /office_hours_schedules/{id} - Destructive
Delete an office hours schedule
You can delete a single office hours schedule.
DELETE /office_hours_schedules/{id}
AI Content
- Read
List content import sources
You can retrieve a list of all content import sources for a workspace. totalcount and pages.totalpages are worked out from every content import source in the workspace, including deleted ones that the list leaves out, so both can be higher than the number of sources you get back across all pages. The last pages can be short or empty. OAuth tokens must have the readwriteaicontent scope.
GET /ai/content_import_sources - Read
Retrieve a content import source
You can retrieve a content import source. OAuth tokens must have the readwriteaicontent scope.
GET /ai/content_import_sources/{source_id} - Read
List external pages
You can retrieve a list of all external pages for a workspace. OAuth tokens must have the readwriteaicontent scope.
GET /ai/external_pages - Read
Retrieve an external page
You can retrieve an external page. OAuth tokens must have the readwriteaicontent scope.
GET /ai/external_pages/{page_id} - Write
Create a content import source
You can create a new content import source by sending a POST request to this endpoint. OAuth tokens must have the readwriteaicontent scope.
POST /ai/content_import_sources - Write
Create an external page (or update an external page by external ID)
You can create a new external page by sending a POST request to this endpoint. If an external page already exists with the specified sourceid and externalid, it will be updated instead. OAuth tokens must have the readwriteaicontent scope.
POST /ai/external_pages - Destructive
Update a content import source
You can update an existing content import source. OAuth tokens must have the readwriteaicontent scope.
PUT /ai/content_import_sources/{source_id} - Destructive
Delete a content import source
You can delete a content import source by making a DELETE request this endpoint. This will also delete all external pages that were imported from this source. OAuth tokens must have the readwriteaicontent scope.
DELETE /ai/content_import_sources/{source_id} - Destructive
Update an external page
You can update an existing external page (if it was created via the API). OAuth tokens must have the readwriteaicontent scope.
PUT /ai/external_pages/{page_id} - Destructive
Delete an external page
Sending a DELETE request for an external page will remove it from the content library UI and from being used for AI answers. OAuth tokens must have the readwriteaicontent scope.
DELETE /ai/external_pages/{page_id}
Articles
- Read
List all articles
You can fetch a list of all articles by making a GET request to https://api.intercom.io/articles. 📘 How are the articles sorted and ordered? Articles will be returned in descending order on the updatedat attribute. This means if you need to iterate through results then we'll show the most recently updated articles first. Requires the readarticlesscope OAuth scope.
GET /articles - Read
Retrieve an article
You can fetch the details of a single article by making a GET request to https://api.intercom.io/articles/ . Requires the readarticlesscope OAuth scope.
GET /articles/{article_id} - Read
Retrieve an article draft
Fetch the staged draft of a published article by making a GET request to https://api.intercom.io/articles/ /draft. The response is the article rendered with its draft content, leaving the live article untouched. A draft exists only when a published article has unpublished changes staged on top of it. Returns 404 with an empty response body when the article has no staged draft. An article ID that doesn't exist returns a 404 with the standard error body. Requires the readarticlesscope OAuth scope.
GET /articles/{id}/draft - Read
List article versions
Fetch the version history of an article by making a GET request to https://api.intercom.io/articles/ /versions. Versions are returned newest-first as a paginated list of metadata. Use GET /articles/{articleid}/versions/{id} to retrieve a single version with its full content. A 404 has an empty response body, whether the article or its content isn't found. Requires the readarticlesscope OAuth scope.
GET /articles/{article_id}/versions - Read
Retrieve an article version
Fetch a single prior version of an article, including its body content, by making a GET request to https://api.intercom.io/articles/ /versions/ . Returns the version's full content; the live article remains untouched. A 404 has an empty response body, whether the article, its content or the version isn't found. Requires the readarticlesscope OAuth scope.
GET /articles/{article_id}/versions/{id} - Read
Search for articles
You can search for articles by making a GET request to https://api.intercom.io/articles/search. If no articles match the search, data is an empty array rather than an object. Requires the readarticlesscope OAuth scope.
GET /articles/search - Write
Create an article
You can create a new article by making a POST request to https://api.intercom.io/articles. 📘 Tags are managed separately Tags are returned in article responses but cannot be set in the request body. To add or remove an article's tags, use the POST /articles/{articleid}/tags and DELETE /articles/{articleid}/tags/{id} endpoints. Requires the readwritearticlesscope OAuth scope.
POST /articles - Write
Publish an article draft
Publish a staged draft by making a POST request to https://api.intercom.io/articles/ /draft/publish, promoting the draft content to live. On a single-language workspace no body is required. On a multilingual workspace you must list which locales to publish via the locales array; omitting it returns 422. Returns 422 when there is no staged draft to publish, or when a requested locale has no pending changes. The 422 for no staged draft has the short body { "errors": [{ "message": "...", "status": 422 }] }, with no type, requestid or code. The other 422 errors use the standard error format. Requires the readwritearticlesscope OAuth scope.
POST /articles/{id}/draft/publish - Write
Add a tag to an article
Apply an existing tag to an article. Returns the tag that was applied. The tag must already exist in the workspace (create tags with the Tags API), and the authenticating teammate must have the manageknowledgebasecontent permission. Requires the readwritearticlesscope OAuth scope.
POST /articles/{article_id}/tags - Destructive
Update an article
You can update the details of a single article by making a PUT request to https://api.intercom.io/articles/ . 📘 Tags are managed separately Tags are returned in article responses but cannot be set in the request body. To add or remove an article's tags, use the POST /articles/{articleid}/tags and DELETE /articles/{articleid}/tags/{id} endpoints. Requires the readwritearticlesscope OAuth scope.
PUT /articles/{article_id} - Destructive
Delete an article
You can delete a single article by making a DELETE request to https://api.intercom.io/articles/ . Requires the readwritearticlesscope OAuth scope.
DELETE /articles/{article_id} - Destructive
Stage an article draft
Stage changes to a published article as a draft by making a PUT request to https://api.intercom.io/articles/ /draft. The live article remains unchanged until the draft is published. The article must already be published; staging a draft on an article that has never been published returns 422. That 422 has the short body { "errors": [{ "message": "...", "status": 422 }] }, with no type, requestid or code. Other 422 errors use the standard error format. Only text content is staged: title, description, body or bodymarkdown, and authorid, including per-locale values in translatedcontent. Any other field in the request body, such as state, parentid, folderid, audienceids, the AI availability fields or the scheduling fields, is still validated but not applied, so the live article is left untouched. The scheduling, state and placement notes on the request schema's other fields do not apply to this endpoint, because those fields are not applied. Requires the readwritearticlesscope OAuth scope.
PUT /articles/{id}/draft - Destructive
Remove a tag from an article
Remove a tag from an article. Returns the tag that was removed, with null appliedat and appliedby. The authenticating teammate must have the manageknowledgebasecontent permission. Requires the readwritearticlesscope OAuth scope.
DELETE /articles/{article_id}/tags/{id}
Away Status Reasons
- Read
List all away status reasons
Returns a list of all away status reasons configured for the workspace, including deleted ones.
GET /away_status_reasons
Audiences
- Read
List all audiences
You can fetch a list of all audiences for the workspace. Requires the readaudiences or readwriteaudiences OAuth scope.
GET /audiences - Read
Retrieve an audience
You can fetch the details of a single audience by making a GET request to https://api.intercom.io/audiences/{id}. Requires the readaudiences or readwriteaudiences OAuth scope.
GET /audiences/{id} - Write
Create an audience
You can create a new audience by making a POST request to https://api.intercom.io/audiences. Requires the readwriteaudiences OAuth scope.
POST /audiences - Destructive
Update an audience
You can update the details of a single audience by making a PUT request to https://api.intercom.io/audiences/{id}. You can also send this request with PATCH; it behaves the same as PUT. Requires the readwriteaudiences OAuth scope.
PUT /audiences/{id} - Destructive
Delete an audience
You can delete a single audience by making a DELETE request to https://api.intercom.io/audiences/{id}. An audience that is still used by other objects, such as a workflow, cannot be deleted. Requires the readwriteaudiences OAuth scope.
DELETE /audiences/{id}
Reporting Data Export
- Read
Get export job status
Requires the exportreportingdata OAuth scope.
GET /export/reporting_data/{job_identifier} - Read
List available datasets and attributes
Requires the exportreportingdata or readreportingdatasets OAuth scope.
GET /export/reporting_data/get_datasets - Read
Download completed export job data
Download the data from a completed reporting data export job. Octet header required You will have to specify the header Accept: application/octet-stream when hitting this endpoint. Requires the exportreportingdata OAuth scope.
GET /download/reporting_data/{job_identifier} - Write
Enqueue a new reporting data export job
For the conversation dataset, from API version 2.16 this export returns all conversations, including those that never received a user reply. Earlier versions return only conversations that received at least one user reply. Other datasets are unaffected. Requires the exportreportingdata OAuth scope.
POST /export/reporting_data/enqueue
Fin Agent
- Write
Start a conversation with Fin
Initialize Fin by passing it the user's message along with conversation history and user details. These additional pieces of context will be used by Fin to provide a better and more contextual answer to the user. {% admonition type="warning" %} To request access to the Fin Agent API, go to Settings Integrations Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent Deploy. {% /admonition %} Once Fin is initialized, it progresses through a series of statuses such as thinking, replying, awaitinguserreply, or resolved before ending with a status of complete. During this workflow, the client should allow Fin to continue uninterrupted until a final complete status is returned via webhook, at which point control of the conversation passes back to the client.
POST /fin/start - Write
Reply to Fin
Once Fin has returned a response to a user's message, its status will be awaitinguserreply. If a user replies, use this endpoint to send this response to Fin. {% admonition type="warning" %} To request access to the Fin Agent API, go to Settings Integrations Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent Deploy. {% /admonition %}
POST /fin/reply - Write
Submit a CSAT rating
Record a customer's satisfaction rating for a conversation, with an optional free-text remark. Fin decides when to ask for a rating — this reuses the CSAT settings on your Fin workflow, not this API. When Fin asks, it fires a csatrequested event over webhooks carrying the rating options to show the user. Present those options, then submit the user's choice here. Submitting the same rating again, with no new remark, is a no-op and stays successful, so an at-least-once client can safely retry. Submitting a different rating updates the stored rating while the update window is still open, and a first remark can be added to an already-rated survey. Once a remark has been recorded the rating is locked and can no longer be changed. {% admonition type="warning" %} To request access to the Fin Agent API, go to Settings Integrations Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent Deploy. {% /admonition %}
POST /fin/csat - Write
Discover Fin's capabilities
Return a machine-readable, per-user list of what Fin can do for a given end user, so an orchestrating agent can decide which endpoint to call. The response is audience-matched to the supplied user: each live, API-triggerable procedure is checked against that user before being included, alongside the static reply, ask, and escalate actions. {% admonition type="warning" %} To request access to the Fin Agent API, go to Settings Integrations Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent Deploy. {% /admonition %}
POST /fin/capabilities - Write
Ask Fin
Ask Fin a single, self-contained question and receive one informational answer. Unlike a conversation, /fin/ask is non-conversational: Fin will not ask follow-up questions, will not run procedures, and will not decide to hand over to a human itself. Escalation rules can still match, and the conversation can still be routed to a team or finish without resolution. You can also escalate one yourself with POST /fin/escalate; the ask conversation is already closed after its one-shot answer, and escalation leaves it closed while routing the handoff separately. Fin's answer is delivered asynchronously via the finreplied event. The conversation ends with a complete status — there is no awaitinguserreply cycle. {% admonition type="warning" %} To request access to the Fin Agent API, go to Settings Integrations Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent Deploy. {% /admonition %}
POST /fin/ask - Write
Run a Fin procedure
Deterministically run a specific procedure on a new conversation. Calling this endpoint guarantees that the named procedure runs — there is no non-deterministic routing. Fin's progress is delivered asynchronously via events. If the procedure pauses for user input, the conversation status becomes awaitinguserreply — send the user's response with /fin/reply. {% admonition type="warning" %} To request access to the Fin Agent API, go to Settings Integrations Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent Deploy. {% /admonition %}
POST /fin/procedures/{procedure_id}/run - Write
Escalate to a human
Hand a conversation off to a human teammate. If you use the Intercom Helpdesk, the handoff lands in your team inbox. Provide either conversationid or user: - conversationid — escalate an existing agent conversation, including one started with /fin/ask. On the Intercom Helpdesk, Fin by default summarises the conversation and opens a new Helpdesk conversation that carries the summary as an internal note. Configure an escalation Operator Workflow to change this default. Escalation closes the original agent conversation if it is open. - user — escalate on behalf of a user with no prior agent conversation. Fin creates an agent conversation for the escalation and closes it once the handoff completes. On the Intercom Helpdesk, the teammate works in a separate new Helpdesk conversation. Not supported on Fin for Platforms — see below. In both cases, pass the optional context to give the receiving teammate background your orchestrating agent has and Fin does not. On the Intercom Helpdesk, it appears above the summary in the internal note of the new conversation the teammate picks up. It is never shown to the end user. Escalating an existing conversation also sets its AI Agent resolution state to escalated, readable as aiagent.resolutionstate on the Conversations API. This is a resolution state, not a billable resolution. On Fin for Platforms, conversationid is required — user is not supported and is rejected, because there is no Intercom Helpdesk in which to create a conversation. There is no Intercom inbox either, so an escalation that no workflow handles does not open a Helpdesk conversation for a teammate. context is not surfaced. The conversation is closed, as on the Intercom Helpdesk, and your platform hands the user off to a human. You are notified via webhooks with an escalated status followed by complete. The complete status signals that Fin is done. By then the original agent conversation has been closed. An escalation Operator Workflow may act on it afterwards, but it is closed again once the workflow's first steps have run, so only steps that run later (for example after a wait) can reopen it. On the Intercom Helpdesk, the new human conversation remains open. {% admonition type="warning" %} To request access to the Fin Agent API, go to Settings Integrations Fin Agent API in your workspace and tell us about your use case. Once access is granted, Fin Agent API appears under Fin AI Agent Deploy. {% /admonition %}
POST /fin/escalate
Help Center
- Read
List all redirects for a help center
You can fetch a list of all URL redirects for a help center by making a GET request to https://api.intercom.io/helpcenter/helpcenters/{helpcenterid}/redirects. Redirects are returned in ascending alphabetical order of fromurl. Requires the readhelpcenterredirectsscope OAuth scope.
GET /help_center/help_centers/{help_center_id}/redirects - Read
Retrieve a redirect
You can fetch the details of a single redirect by making a GET request to https://api.intercom.io/helpcenter/helpcenters/{helpcenterid}/redirects/{id}. Requires the readhelpcenterredirectsscope OAuth scope.
GET /help_center/help_centers/{help_center_id}/redirects/{id} - Read
List all collections
You can fetch a list of all collections by making a GET request to https://api.intercom.io/helpcenter/collections. Requires the readarticlesscope OAuth scope.
GET /help_center/collections - Read
Retrieve a collection
You can fetch the details of a single collection by making a GET request to https://api.intercom.io/helpcenter/collections/ . Requires the readarticlesscope OAuth scope.
GET /help_center/collections/{collection_id} - Read
Retrieve a Help Center
You can fetch the details of a single Help Center by making a GET request to https://api.intercom.io/helpcenter/helpcenters/ . Requires the readarticlesscope OAuth scope.
GET /help_center/help_centers/{help_center_id} - Read
List all Help Centers
You can list all Help Centers by making a GET request to https://api.intercom.io/helpcenter/helpcenters. Requires the readarticlesscope OAuth scope.
GET /help_center/help_centers - Write
Create a redirect
You can create a new URL redirect by making a POST request to https://api.intercom.io/helpcenter/helpcenters/{helpcenterid}/redirects. Requires the readwritehelpcenterredirectsscope OAuth scope.
POST /help_center/help_centers/{help_center_id}/redirects - Write
Create a collection
You can create a new collection by making a POST request to https://api.intercom.io/helpcenter/collections. Requires the readwritearticlesscope OAuth scope.
POST /help_center/collections - Destructive
Delete a redirect
You can delete a single redirect by making a DELETE request to https://api.intercom.io/helpcenter/helpcenters/{helpcenterid}/redirects/{id}. Requires the readwritehelpcenterredirectsscope OAuth scope.
DELETE /help_center/help_centers/{help_center_id}/redirects/{id} - Destructive
Update a collection
You can update the details of a single collection by making a PUT request to https://api.intercom.io/helpcenter/collections/ . helpcenterid is checked but never applied. It must match the help center of the collection's articles and sub-collections, or the request returns a 400. A collection with no content rejects any helpcenterid, so leave it out. Moving a collection to another help center isn't supported. Requires the readwritearticlesscope OAuth scope.
PUT /help_center/collections/{collection_id} - Destructive
Delete a collection
You can delete a single collection by making a DELETE request to https://api.intercom.io/helpcenter/collections/ . Requires the readwritearticlesscope OAuth scope.
DELETE /help_center/collections/{collection_id}
Internal Articles
- Read
List all articles
You can fetch a list of all internal articles by making a GET request to https://api.intercom.io/internalarticles. Requires the readarticlesscope or readwritearticlesscope OAuth scope.
GET /internal_articles - Read
Retrieve an internal article
You can fetch the details of a single internal article by making a GET request to https://api.intercom.io/internalarticles/ . Requires the readarticlesscope or readwritearticlesscope OAuth scope.
GET /internal_articles/{internal_article_id} - Read
Search for internal articles
You can search for internal articles by making a GET request to https://api.intercom.io/internalarticles/search. Requires the readwritearticlesscope OAuth scope.
GET /internal_articles/search - Write
Create an internal article
You can create a new internal article by making a POST request to https://api.intercom.io/internalarticles. Requires the readwritearticlesscope OAuth scope.
POST /internal_articles - Write
Add a tag to an internal article
Apply an existing tag to an internal article. Returns the tag that was applied. The tag must already exist in the workspace (create tags with the Tags API), and the authenticating teammate must have the manageknowledgebasecontent permission. Requires the readwritearticlesscope OAuth scope.
POST /internal_articles/{internal_article_id}/tags - Destructive
Update an internal article
You can update the details of a single internal article by making a PUT request to https://api.intercom.io/internalarticles/ . Fields you leave out keep their current values. Requires the readwritearticlesscope OAuth scope.
PUT /internal_articles/{internal_article_id} - Destructive
Delete an internal article
You can delete a single internal article by making a DELETE request to https://api.intercom.io/internalarticles/ . Requires the readwritearticlesscope OAuth scope.
DELETE /internal_articles/{internal_article_id} - Destructive
Remove a tag from an internal article
Remove a tag from an internal article. Returns the tag that was removed, with null appliedat and appliedby. The authenticating teammate must have the manageknowledgebasecontent permission. Requires the readwritearticlesscope OAuth scope.
DELETE /internal_articles/{internal_article_id}/tags/{id}
Folders
- Read
List all folders
You can fetch a list of all folders for organizing content by making a GET request to https://api.intercom.io/folders. Requires the readarticlesscope or readwritearticlesscope OAuth scope.
GET /folders - Read
Retrieve a folder
You can fetch the details of a single folder by making a GET request to https://api.intercom.io/folders/ . Requires the readarticlesscope or readwritearticlesscope OAuth scope.
GET /folders/{id} - Write
Create a folder
You can create a new folder for organizing content by making a POST request to https://api.intercom.io/folders. Requires the readwritearticlesscope OAuth scope.
POST /folders - Destructive
Update a folder
You can update a folder by making a PUT request to https://api.intercom.io/folders/ . Fields you leave out keep their current values. Send parentfolderid as null to move the folder to the top level. Folder names longer than 191 characters are truncated. Requires the readwritearticlesscope OAuth scope.
PUT /folders/{id} - Destructive
Delete a folder
You can delete a folder (if it contains no content) by making a DELETE request to https://api.intercom.io/folders/ . Requires the readwritearticlesscope OAuth scope.
DELETE /folders/{id}
IP Allowlist
- Read
Get IP allowlist settings
Retrieve the current IP allowlist configuration for the workspace. Requires the manageipallowlist OAuth scope.
GET /ip_allowlist - Destructive
Update IP allowlist settings
Update the IP allowlist configuration for the workspace. Both enabled and ipallowlist are optional. A field you omit is left unchanged, and a request with neither returns the current settings without changing anything. Sending null for a field is the same as omitting it. Every non-blank ipallowlist entry must be an IPv4 address or an IPv4 range in CIDR notation. Blank entries are ignored and surrounding whitespace is trimmed. Any other entry, including an IPv6 address, returns a 422 parameterinvalid error. When the update leaves the allowlist enabled with at least one entry, the request must come from an IPv4 address that is on the list. A request from an IPv6 address can never match an IPv4 allowlist, so it returns the lockout 422 below. Requires the manageipallowlist OAuth scope. {% admonition type="warning" name="Lockout Protection" %} The API will reject updates that would lock out the caller's IP address. Ensure your current IP is included in the allowlist when enabling the feature. {% /admonition %}
PUT /ip_allowlist
Companies
- Read
Retrieve companies
You can fetch a single company by passing in companyid or name. https://api.intercom.io/companies?name={name} https://api.intercom.io/companies?companyid={companyid} You can fetch all companies and filter by segmentid or tagid as a query parameter. https://api.intercom.io/companies?tagid={tagid} https://api.intercom.io/companies?segmentid={segmentid} The list is paged by page number. There is a limit of 10,000 companies; beyond that the request returns a 400 error and you should use the scroll endpoint instead.
GET /companies - Read
Retrieve a company by ID
You can fetch a single company.
GET /companies/{company_id} - Read
List attached contacts
You can fetch a list of all contacts that belong to a company. Requires the readuserscompanies OAuth scope.
GET /companies/{company_id}/contacts - Read
List attached segments for companies
You can fetch a list of all segments that belong to a company. Requires the readuserscompanies OAuth scope.
GET /companies/{company_id}/segments - Read
Search companies
You can search for companies by the value of their attributes in order to fetch exactly the companies you want. To search for companies, send a POST request to https://api.intercom.io/companies/search, with a query object in the body defining your filters. Note that the API does not include companies who have no associated users in search results. {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 15 results per page. See the pagination section for more details on how to use the startingafter param. {% /admonition %} Nesting & Limitations You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be: There's a limit of max 2 nested filters There's a limit of max 15 filters for each AND or OR group Accepted Fields Most keys listed as part of the Companies Model are searchable. The value you search for has to match the accepted type, otherwise the query will fail (ie. as createdat accepts a date, the value cannot be a string such as "foobar"). | Field | Type | | ---------------------------------- | ------------------------------ | | companyid | String | | name | String | | createdat | Date (UNIX Timestamp) | | updatedat | Date (UNIX Timestamp) | | remotecreatedat | Date (UNIX Timestamp) | | lastrequestat | Date (UNIX Timestamp) | | monthlyspend | Integer | | sessioncount | Integer | | usercount | Integer | | tagid | String | | customattributes.{attributename} | String | The plan.id and plan.name fields are not searchable and return a 400 error with code invalidfield. Accepted Operators The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string ("="). The operator has to be compatible with the field's type (eg. you cannot search with for a given string value as it's only compatible for integer's and dates). Searching by tagid supports only the = and != operators. The IN and NIN operators are not supported for Date fields. | Operator | Valid Types | Description | | :------- | :------------------------------- | :--------------------------------------------------------------- | | = | All | Equals | | != | All | Doesn't Equal | | IN | All except Date and tagid | In Shortcut for OR queries Values must be in Array | | NIN | All except Date and tagid | Not In Shortcut for OR ! queries Values must be in Array | | | Integer Date (UNIX Timestamp) | Greater than | | Date (UNIX Timestamp) | Lower than | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With | Sorting Pass an optional sort object with a field and an order (ascending or descending; defaults to descending) to order the results. An invalid order returns a 400 error with code invalidsortorder. tagid can be used as a filter but not as a sort field. Pagination Pass an optional pagination object with perpage and startingafter. perpage defaults to 15 and must be between 1 and 150; anything else returns a 400 error with code invalidperpage. Take startingafter from pages.next in the previous response, and send it with the same sort you used for that response. A cursor from a sort on a text field such as name, sent with a sort on a number or date field (or the other way round), returns a 400 error with code clienterror. Leaving out sort sorts by lastrequestat, a date. A cursor sent with a different sort of the same kind is accepted, but the page it returns doesn't follow on from the previous one. Requires the readuserscompanies OAuth scope.
POST /companies/search - Read
List all companies
You can list companies. The company list is sorted by the lastrequestat field and by default is ordered descending, most recently requested first. Note that the API does not include companies who have no associated users in list responses. When using the Companies endpoint and the pages object to iterate through the returned companies, there is a limit of 10,000 Companies that can be returned. If you need to list or iterate on more than 10,000 Companies, please use the Scroll API. Going past that limit returns a 400 error with code badrequest. {% admonition type="warning" name="Pagination" %} This endpoint pages by page number, not by cursor. Use the page and perpage query parameters, and the page, totalpages and next values in the pages object of the response. The default is 15 results per page. See the pagination section for more details. {% /admonition %} Requires the writeuserscompanies OAuth scope. A token with only read scopes cannot call this endpoint.
POST /companies/list - Read
Scroll over all companies
The list all companies functionality does not work well for huge datasets, and can result in errors and performance problems when paging deeply. The Scroll API provides an efficient mechanism for iterating over all companies in a dataset. - Each app can only have 1 scroll open at a time. Starting a second one returns a 400 error with code scrollexists. - If the scroll isn't used for 1 minute, it expires and calls with that scroll param return a 404 error with code notfound. - If the end of the scroll is reached, data will be empty and the scroll parameter will expire. The response always has pages and totalcount set to null. Use scrollparam to fetch the next page. {% admonition type="info" name="Scroll Parameter" %} You can get the first page of companies by simply sending a GET request to the scroll endpoint. For subsequent requests you will need to use the scroll parameter from the response. {% /admonition %} {% admonition type="danger" name="Scroll network timeouts" %} Since scroll is often used on large datasets network errors such as timeouts can be encountered. When this occurs you will see a HTTP 500 error with the following message: "Request failed due to an internal network error. Please restart the scroll operation." If this happens, you will need to restart your scroll query: It is not possible to continue from a specific point when using scroll. {% /admonition %} Requires the readuserscompanies OAuth scope.
GET /companies/scroll - Write
Create or Update a company
You can create or update a company. Companies will be only visible in Intercom when there is at least one associated user. Companies are looked up via companyid in a POST request, if not found via companyid, the new company will be created, if found, that company will be updated. You must send either companyid or id. A request with neither returns a 400 error. Every custom attribute you send must already exist in your workspace. Sending one that doesn't returns a 400 error. {% admonition type="warning" name="Using companyid" %} You can set a unique companyid value when creating a company. However, it is not possible to update companyid. Be sure to set a unique value once upon creation of the company. {% /admonition %} Requires the writeuserscompanies OAuth scope.
POST /companies - Write
Attach a Contact to a Company
You can attach a company to a single contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/{contact_id}/companies - Destructive
Update a company
You can update a single company using the Intercom provisioned id. Every custom attribute you send must already exist in your workspace. Sending one that doesn't returns a 400 error. You can also send this request with PATCH; it behaves the same as PUT. {% admonition type="warning" name="Using companyid" %} When updating a company it is not possible to update companyid. This can only be set once upon creation of the company. {% /admonition %} Requires the writeuserscompanies OAuth scope.
PUT /companies/{company_id} - Destructive
Delete a company
Delete a single company. The company record is kept in your workspace, but all contacts are detached. The contacts themselves are not deleted. Detaching contacts is permanent and can't be reversed. These changes may take some time to be reflected in your workspace. The response returns "deleted": true as soon as the request is accepted; the contacts are detached in the background. A company.deleted webhook is sent after that work finishes, so it arrives some time after the response. No webhook is sent for a company that has no contacts attached, because there is nothing to detach. {% admonition type="warning" %} Third-party integrations that sync companies into Intercom (for example, Salesforce or Chargebee) will recreate any company deleted through this endpoint on their next sync. To prevent recreation, remove or filter the company at the source integration before deleting it via the API. {% /admonition %} Requires the writeuserscompanies OAuth scope.
DELETE /companies/{company_id} - Destructive
Detach a contact from a company
You can detach a company from a single contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
DELETE /contacts/{contact_id}/companies/{company_id}
Notes
- Read
List all company notes
You can fetch a list of notes that are associated to a company. Requires the readuserscompanies OAuth scope.
GET /companies/{company_id}/notes - Read
List all notes
You can fetch a list of notes that are associated to a contact. Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts/{contact_id}/notes - Read
Retrieve a note
You can fetch the details of a single note.
GET /notes/{note_id} - Write
Create a company note
You can add a note to a single company. Requires the writeuserscompanies OAuth scope.
POST /companies/{company_id}/notes - Write
Create a note
You can add a note to a single contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/{contact_id}/notes - Destructive
Delete a note
You can delete a single contact or company note. Notes of other kinds cannot be deleted through the API. Requires the writeuserscompanies OAuth scope.
DELETE /notes/{note_id}
Contacts
- Read
List attached companies for contact
You can fetch a list of companies that are associated to a contact.
GET /contacts/{contact_id}/companies - Read
List attached segments for contact
You can fetch a list of segments that are associated to a contact. Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts/{contact_id}/segments - Read
List subscriptions for a contact
You can fetch a list of subscription types that are attached to a contact. These can be subscriptions that a user has 'opted-in' to or has 'opted-out' from, depending on the subscription type. This will return a list of Subscription Type objects that the contact is associated with. The data property will show a combined list of: 1.Opt-out subscription types that the user has opted-out from. 2.Opt-in subscription types that the user has opted-in to receiving. Note: This endpoint only returns subscriptions where the contact has explicitly configured their preference. Subscriptions that are in the default state — where the contact has not made an explicit opt-in or opt-out choice — are not included in the response.
GET /contacts/{contact_id}/subscriptions - Read
List tags attached to a contact
You can fetch a list of all tags that are attached to a specific contact.
GET /contacts/{contact_id}/tags - Read
List deleted contacts
Fetch a paginated list of the contacts in your workspace that are no longer active, so you can recover ones whose id, email, or externalid you no longer have and then permanently delete them. Each entry carries a status describing why the contact is inactive: archived, blocked, merged, pendingdeletion, or permanentlydeleted. mergedintoid is present only when status is merged, and externalid and email are null for permanentlydeleted contacts. Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts/deleted - Read
Get a contact
You can fetch the details of a single contact. {% admonition type="info" name="Merged contacts return 410 Gone" %} If a contact has been merged into another contact via the Merge endpoint (POST /contacts/merge), requesting it by its original ID will return HTTP 410 Gone with a Link header pointing to the canonical (merged-into) contact. Response headers: Link: ; rel="canonical" Response body: json { "type": "error.list", "errors": [{ "code": "contactmerged", "message": "This contact has been merged. See the 'Link' header for the canonical contact." }] } The Link header contains the path to the final merge target, resolving multi-hop merge chains (up to 3 hops). {% /admonition %} Requires the readsingleuser, readuserscompanies or readwriteusers OAuth scope.
GET /contacts/{contact_id} - Read
Preview a contact merge
Preview the result of merging one contact into another without applying the merge. This is a read-only dry run: it reports whether the merge is allowed and, if so, exactly what would change, without modifying any data. Send the same from and into contact IDs you would pass to Merge two contacts. You can merge a contact with a role of lead into a contact with a role of user. You can optionally pass customattributenames to include specific custom attributes in the previewed attribute changes. - When allowed is true, the response contains a summary: every attribute change (with the resulting value on the surviving contact) and, for each object type, two counts — from, how many are on the source contact and would move to the destination, and into, how many the destination already has. Counts are reported for conversations, tickets, phone calls, notes, and tags. conversations counts non-ticket conversations only; tickets are reported separately under tickets, and phonecalls is present only for phone-channel merges. - When allowed is false, the response contains reasons. Each reason has a stable code you can branch on and a human-readable message you can display. {% admonition type="warning" name="Previewing non-duplicate contacts" %} By default a merge requires the two contacts to share an identifier (email or phone). Set skipduplicatevalidation to true to preview a merge of contacts that don't, the same rule the merge endpoint enforces. {% /admonition %} When allowed is false, reasons[].code is one of: | code | meaning | | --- | --- | | sourcesameastarget | The source contact (from) and the destination contact (into) are the same contact. A contact can't be merged into itself. | | invalidmergerolepair | The from/into roles aren't mergeable. into must be a user. | | nosharedidentifier | The contacts share no email or phone. The source's phone also counts as shared when it matches the destination's WhatsApp number. Set skipduplicatevalidation to preview anyway. | | facebookuser | Facebook contacts can't be merged. | | externalleadchannelnotallowed | The source is an external-channel lead that isn't eligible for merging. | | mailinglist | Contacts created from a mailing list can't be merged. | | whatsappdatacannotbemerged | The WhatsApp number on the source contact can't be reassigned to the destination. | | telegramdatacannotbemerged | The Telegram sender on the source contact can't be reassigned to the destination. | | msteamsdatacannotbemerged | The destination contact already has a Microsoft Teams sender for the same team as the source contact, so the source's sender can't be reassigned to it. | | phonedatacannotbemerged | The phone data on the source contact can't be reassigned to the destination. | Requires the readwriteusers OAuth scope.
POST /contacts/merge/preview - Read
Search contacts
You can search for multiple contacts by the value of their attributes in order to fetch exactly who you want. To search for contacts, you need to send a POST request to https://api.intercom.io/contacts/search. This will accept a query object in the body which will define your filters in order to search for contacts. {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 50 results per page. See the pagination section for more details on how to use the startingafter param. {% /admonition %} Merged Contacts Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by updatedat or any other field. Only the target contact from the merge remains searchable. Contact Creation Delay If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters. Nesting & Limitations You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be: There's a limit of max 2 nested filters There's a limit of max 15 filters for each AND or OR group There's a limit of max 15 values in an IN or NIN array pagination.perpage must be between 1 and 150 Searching for Timestamp Fields Standard timestamp fields and Date custom attributes behave differently. Standard timestamp fields (createdat, updatedat, lastseenat etc.) are filtered on the exact second, in UTC. = matches only Contacts whose value is that exact second, and , = and matches from the start of the next UTC day, and =, Accepts user or lead; contact is treated as lead | | name | String | | avatar | String | | ownerid | Integer | | email | String | | emaildomain | String | | phone | String | | externalid | String | | createdat | Datetime (Unix timestamp in seconds) | | signedupat | Datetime (Unix timestamp in seconds) | | updatedat | Datetime (Unix timestamp in seconds) | | lastseenat | Datetime (Unix timestamp in seconds) | | lastcontactedat | Datetime (Unix timestamp in seconds) | | lastrepliedat | Datetime (Unix timestamp in seconds) | | lastemailopenedat | Datetime (Unix timestamp in seconds) | | lastemailclickedat | Datetime (Unix timestamp in seconds) | | languageoverride | String | | browser | String | | browserversion | String | | browserlanguage | String | | os | String | | location.country | String | | location.region | String | | location.city | String | | unsubscribedfromemails | Boolean | | markedemailasspam | Boolean | | hashardbounced | Boolean | | phonecountry | String | | slackemail | String | | finqualificationstatus | String | | whatsappnumber | String Only on workspaces with the WhatsApp integration | | ioslastseenat | Datetime (Unix timestamp in seconds) | | iosappversion | String | | iosdevice | String | | iososversion | String | | iosappname | String | | iossdkversion | String | | androidlastseenat | Datetime (Unix timestamp in seconds) | | androidappversion | String | | androiddevice | String | | androidosversion | String | | androidappname | String | | androidsdkversion | String | | enabledpushmessaging | Boolean | | segmentid | String | | tagid | String | | customattributes.{attributename} | Matches the attribute's own type (String, Integer, Float, Boolean or Date) | The ios fields other than iosappname are searchable only once your workspace has been set up for the Intercom iOS SDK or has received a request from it, and the android fields other than androidappname only once the same is true for the Android SDK. enabledpushmessaging needs either. Until then, they return an invalidfield error. Accepted Operators {% admonition type="warning" name="Operators not supported on Date custom attributes" %} Date custom attributes do not support the !=, =, or Also matches Contacts with no value set | | IN | All except Date, Datetime, tagid and segmentid | In Shortcut for OR queries Values must be in Array | | NIN | All except Date, Datetime, tagid and segmentid | Not In Shortcut for OR ! queries Values must be in Array | | | Integer Float Datetime Date | Greater than On Date custom attributes, matches from the start of the next day | | Float Datetime Date | Lower than On Date custom attributes, matches before the start of the day | | = | Integer Float Datetime | Greater than or equal to Not supported on Date custom attributes | | Float Datetime | Lower than or equal to Not supported on Date custom attributes | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With | Requires the readuserscompanies or readwriteusers OAuth scope.
POST /contacts/search - Read
List all contact activities
You can fetch a list of contact activity events for your workspace, such as when contacts are created, role updated, merged, or deleted. Events are returned oldest first. If the activity store can't be read, this endpoint returns 200 with an empty data array and no pages.next, the same response as when there are no new events. {% admonition type="warning" name="Pagination" %} You can use pagination to limit the number of results returned. The default is 50 results per page, with a maximum of 150. See the pagination section for more details on how to use the startingafter param. {% /admonition %} Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts/activities - Read
List all contacts
You can fetch a list of all contacts (ie. users or leads) in your workspace. {% admonition type="info" name="Merged contacts" %} Contacts that have been merged (via POST /contacts/merge) will not appear in list results. Only the target contact from the merge remains accessible. {% /admonition %} {% admonition type="warning" name="Pagination" %} You can use pagination to limit the number of results returned. The default is 10 results per page, with a maximum of 150. See the pagination section for more details on how to use the startingafter param. {% /admonition %} Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts - Read
Get a contact by External ID
You can fetch the details of a single contact by external ID. Note that this endpoint only supports users and not leads. {% admonition type="info" name="Merged contacts return 410 Gone" %} If the contact with this external ID has been merged into another contact, the API returns HTTP 410 Gone with a Link header pointing to the canonical (merged-into) contact. See GET /contacts/{id} for details on the response format. {% /admonition %} Requires the readsingleuser, readuserscompanies or readwriteusers OAuth scope.
GET /contacts/find_by_external_id/{external_id} - Read
Get contact merge history
Retrieve the paginated list of contacts that have been merged into a given contact. Only available for contacts with a user role. Returns a 404 if the contact is not found or has a lead role. Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts/{id}/merge_histories - Read
Get a bulk update job
You can check the status of a bulk contact update job. The state field indicates the overall job progress: running, completed, or completedwitherrors. Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts/bulk/{id} - Write
Create contact
You can create a new contact (ie. user or lead). Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts - Write
Unarchive contact
You can unarchive a single contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/{contact_id}/unarchive - Write
Block contact
Block a single contact. Note: conversations of the contact will also be archived during the process. More details in FAQ How do I block Inbox spam? Requires the readwriteusers OAuth scope.
POST /contacts/{contact_id}/block - Write
Bulk create contacts
You can bulk create contacts by submitting an array of contact objects. This is a strict create and never updates an existing contact. The endpoint creates an async job that processes the items in the background. Use the returned job ID with GET /contacts/bulk/{id} to check the job status. Only the fields listed in the request schema below can be set. Any other fields in a contact object are ignored. {% admonition type="info" name="Handling existing contacts" %} If a contact already exists with the given externalid or email (including an archived contact), that item is rejected and the job's state ends as completedwitherrors. New contacts in the same request are still created. The job state from GET /contacts/bulk/{id} is the signal that one or more items were rejected. Created contacts aren't returned with IDs in the response. Look them up afterwards with Get a contact by External ID or Search contacts. {% /admonition %} {% admonition type="info" name="Limits" %} - Maximum of 100 contacts per request. - You can append tasks to an existing job by including job.id in the request body. - Tag application is best-effort and processed asynchronously: unknown tag IDs are skipped, and per-tag results are not returned in the job status. {% /admonition %} Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/bulk - Destructive
Update a contact
You can update an existing contact (ie. user or lead). {% admonition type="info" %} This endpoint handles both contact updates and custom object associations. See update a contact with an association to a custom object instance in the request/response examples to see the custom object association format. {% /admonition %} Requires the readwriteusers or writeuserscompanies OAuth scope.
PUT /contacts/{contact_id} - Destructive
Delete a contact
You can delete a single contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
DELETE /contacts/{contact_id} - Destructive
Merge a lead and a user
You can merge a contact with a role of lead into a contact with a role of user. {% admonition type="warning" name="Merged contacts are not retrievable via the API" %} Once a merge is completed, the source contact (from) is permanently removed from the active contact list. This means: - GET /contacts/{id} — Requesting the source contact by its original ID returns 410 Gone with a Link header pointing to the contact it was merged into. See Get a contact. - POST /contacts/search — The source contact will not appear in search results, including queries filtered by updatedat. - GET /contacts — The source contact will not appear in list results. Only the target contact (into) remains accessible. If your application stores contact IDs, update them to use the target contact's ID after a merge. {% /admonition %} Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/merge - Destructive
Archive contact
You can archive a single contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/{contact_id}/archive - Destructive
Bulk update contacts
You can bulk update contacts by submitting an array of contact objects with the fields to update. Each contact must include an id field identifying the contact to update. You can also add or remove tags on each contact by including a tags object. Only the fields listed in the request schema below can be set. Any other fields in a contact object are ignored. The endpoint creates an async job that processes the updates in the background. Use the returned job ID with GET /contacts/bulk/{id} to check the job status. {% admonition type="info" name="Limits" %} - Maximum of 100 contacts per request. - You can append tasks to an existing job by including job.id in the request body. - Tag application is best-effort and processed asynchronously: unknown tag IDs are skipped, and per-tag results are not returned in the job status. {% /admonition %} Requires the readwriteusers or writeuserscompanies OAuth scope.
PUT /contacts/bulk - Destructive
Bulk delete contacts
You can delete contacts in bulk by submitting an array of contact ids. The endpoint creates an async job that processes the deletes in the background. Use the returned job ID with GET /contacts/bulk/{id} to check the job status. {% admonition type="warning" name="Permanent deletion" %} A contact that doesn't exist, or can't be deleted, fails that item and the job's state ends as completedwitherrors (visible via GET /contacts/bulk/{id}) without failing the rest of the batch. {% /admonition %} {% admonition type="info" name="Limits" %} - Maximum of 1,000 contacts per request. - You can append tasks to an existing job by including job.id in the request body. {% /admonition %} Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/bulk/delete
Subscription Types
- Read
List subscription types
You can list all subscription types. A list of subscription type objects will be returned. Requires the readuserscompanies OAuth scope.
GET /subscription_types - Read
Retrieve a subscription type
You can fetch the details of a single subscription type by making a GET request to https://api.intercom.io/subscriptiontypes/ . Requires the readuserscompanies OAuth scope.
GET /subscription_types/{id} - Write
Add subscription to a contact
You can add a specific subscription to a contact. In Intercom, we have two different subscription types based on user consent - opt-out and opt-in: 1.Attaching a contact to an opt-out subscription type will opt that user out from receiving messages related to that subscription type. 2.Attaching a contact to an opt-in subscription type will opt that user in to receiving messages related to that subscription type. This will return a subscription type model for the subscription type that was added to the contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/{contact_id}/subscriptions - Destructive
Remove subscription from a contact
You can remove a specific subscription from a contact. This will return a subscription type model for the subscription type that was removed from the contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
DELETE /contacts/{contact_id}/subscriptions/{subscription_id}
Tags
- Read
List all tags
You can fetch a list of all tags for a given workspace. Passing id returns that one tag object instead of a list. Passing taggabletype returns a list of the tags applied to a single contact or company. Requires the readtags or readuserscompanies OAuth scope.
GET /tags - Read
Find a specific tag
You can fetch the details of tags that are on the workspace by their id. This will return a tag object. Requires the readtags or readuserscompanies OAuth scope.
GET /tags/{tag_id} - Write
Add tag to a contact
You can tag a specific contact. This will return a tag object for the tag that was added to the contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /contacts/{contact_id}/tags - Write
Add tag to a conversation
You can tag a specific conversation. This will return a tag object for the tag that was added to the conversation.
POST /conversations/{conversation_id}/tags - Write
Add tag to a ticket
You can tag a specific ticket. This will return a tag object for the tag that was added to the ticket.
POST /tickets/{ticket_id}/tags - Destructive
Remove tag from a contact
You can remove tag from a specific contact. This will return a tag object for the tag that was removed from the contact. Requires the readwriteusers or writeuserscompanies OAuth scope.
DELETE /contacts/{contact_id}/tags/{tag_id} - Destructive
Remove tag from a conversation
You can remove tag from a specific conversation. This will return a tag object for the tag that was removed from the conversation.
DELETE /conversations/{conversation_id}/tags/{tag_id} - Destructive
Create or update a tag, Tag or untag companies, Tag contacts
You can use this endpoint to perform the following operations: 1. Create a new tag: You can create a new tag by passing in the tag name as specified in "Create or Update Tag Request Payload" described below. 2. Update an existing tag: You can update an existing tag by passing the id of the tag as specified in "Create or Update Tag Request Payload" described below. 3. Tag Companies: You can tag single company or a list of companies. You can tag a company by passing in the tag name and the company details as specified in "Tag Company Request Payload" described below. Also, if the tag doesn't exist then a new one will be created automatically. 4. Untag Companies: You can untag a single company or a list of companies. You can untag a company by passing in the tag id and the company details as specified in "Untag Company Request Payload" described below. 5. Tag Multiple Users: You can tag a list of users. You can tag the users by passing in the tag name and the user details as specified in "Tag Users Request Payload" described below. Each operation will return a tag object. Contacts and companies listed in users or companies that do not exist are skipped: they are left out of the users and companies arrays in the response and the request still succeeds. With idstoadd it depends on taggabletype: a contact id that does not exist returns a 404, while a company id that does not exist is skipped. With idstoadd, the users and companies arrays in the response are always empty, and a 404 still leaves the tag created or renamed. Requires the writetags or writeuserscompanies OAuth scope.
POST /tags - Destructive
Delete tag
You can delete the details of tags that are on the workspace by passing in the id. Requires the writetags or writeuserscompanies OAuth scope.
DELETE /tags/{tag_id} - Destructive
Remove tag from a ticket
You can remove tag from a specific ticket. This will return a tag object for the tag that was removed from the ticket.
DELETE /tickets/{ticket_id}/tags/{tag_id}
Banners
- Read
List banners for a contact
Returns the banners a contact currently matches, so you can display them on surfaces outside the Messenger (native mobile apps, kiosks, embedded tools). Each banner in the response includes a viewid. Use it to record a dismissal with the dismiss endpoint. A returned banner is treated as shown: requesting this endpoint records an impression for each banner returned, so call it at the point you are about to display the banners, not speculatively. Requires the readuserscompanies or readwriteusers OAuth scope.
GET /contacts/{id}/banners - Write
Dismiss a banner for a contact
Records that a contact has dismissed a banner. Dismissals are shared across surfaces, so a banner dismissed through this endpoint will also stop appearing in the web Messenger for that contact, and vice versa. The request is idempotent: dismissing an already-dismissed banner succeeds and returns the same response. Requires the readwriteusers OAuth scope.
POST /contacts/{id}/banners/{view_id}/dismiss
Content
- Read
Search knowledge base contents
Search the knowledge base contents — articles, snippets, external pages, uploaded files, and internal articles — using a keyword query. Each result row has a type discriminator. Most types (contentsnippet, externalcontent, filesourcecontent, internalarticle) return a flat { type, id, title } shape. Help center articles return a nested shape with a contents[] array, one entry per locale. Requires the readcontent OAuth scope.
GET /content/search - Destructive
Run a bulk action on Knowledge Hub content
Asynchronously run a bulk action over up to 1,000 Knowledge Hub content items. Six actions are supported: publish and unpublish — apply to articlecontent only. delete — permanently delete content (excludes synced sources and externalcontent). setavailability — toggle Fin AI Agent, Copilot, and Sales Agent availability flags. setaudience — manage segment membership on content. updatetags — apply and/or remove existing tags on content. Unlike the other actions, updatetags addresses articles by the parent article id, not articlecontent. Tags must already exist and not be archived; supply at least one of addtagids / removetagids. The endpoint validates the request, enqueues background work, and returns 202 with a placeholder envelope. Items whose type is not in the action's allowlist are silently dropped before processing. Articles imported from synced sources (Confluence, Notion, Zendesk, Salesforce Knowledge, etc.) are silently skipped on delete — they can only be removed by disconnecting the underlying import source. Requires the writecontent OAuth scope.
POST /content/bulk_actions
Content Snippets
- Read
List all content snippets
You can fetch a list of all content snippets for a workspace. Requires the readcontentsnippets or readwritecontentsnippets OAuth scope.
GET /content_snippets - Read
Retrieve a content snippet
You can fetch a single content snippet by its id. Requires the readcontentsnippets or readwritecontentsnippets OAuth scope.
GET /content_snippets/{id} - Write
Create a content snippet
You can create a new content snippet. title is listed as required, but a missing, null or empty title is accepted and the snippet is created with a blank title. When jsonblocks is omitted or null and bodymarkdown is omitted or blank, the snippet is created with a single empty paragraph. Requires the readwritecontentsnippets OAuth scope.
POST /content_snippets - Write
Add a tag to a content snippet
Apply an existing tag to a content snippet. Returns the tag that was applied. The tag must already exist in the workspace (create tags with the Tags API), and the authenticating teammate must have the manageknowledgebasecontent permission. Requires the readwritecontentsnippets OAuth scope.
POST /content_snippets/{content_snippet_id}/tags - Destructive
Update a content snippet
You can update an existing content snippet. Requires the readwritecontentsnippets OAuth scope.
PUT /content_snippets/{id} - Destructive
Delete a content snippet
You can delete a single content snippet by its id. Requires the readwritecontentsnippets OAuth scope.
DELETE /content_snippets/{id} - Destructive
Remove a tag from a content snippet
Remove a tag from a content snippet. Returns the tag that was removed, with null appliedat and appliedby. The authenticating teammate must have the manageknowledgebasecontent permission. Requires the readwritecontentsnippets OAuth scope.
DELETE /content_snippets/{content_snippet_id}/tags/{id}
Dynamic Content
- Read
List all dynamic content
You can fetch a list of all dynamic content for a workspace, most recently updated first. Requires the readdynamiccontent or readwritedynamiccontent OAuth scope.
GET /dynamic_contents - Read
Retrieve dynamic content
You can fetch a single dynamic content by its id. Requires the readdynamiccontent or readwritedynamiccontent OAuth scope.
GET /dynamic_contents/{id} - Write
Create dynamic content
You can create dynamic content. Requires the readwritedynamiccontent OAuth scope.
POST /dynamic_contents - Destructive
Update dynamic content
You can update existing dynamic content. Only the fields you provide are changed. You can also send this request with PATCH; it behaves the same as PUT. Requires the readwritedynamiccontent OAuth scope.
PUT /dynamic_contents/{id} - Destructive
Delete dynamic content
You can delete a single dynamic content by its id. Dynamic content that is still used in an article can't be deleted. Requires the readwritedynamiccontent OAuth scope.
DELETE /dynamic_contents/{id}
Conversations
- Read
List all conversations
You can fetch a list of all conversations. You can optionally request the result page size and the cursor to start after to fetch the result. {% admonition type="warning" name="Pagination" %} You can use pagination to limit the number of results returned. The default is 20 results per page. See the pagination section for more details on how to use the startingafter param. {% /admonition %}
GET /conversations - Read
Retrieve a conversation
You can fetch the details of a single conversation. This will return a single Conversation model with all its conversation parts. {% admonition type="warning" name="Hard limit of 500 parts" %} The maximum number of conversation parts that can be returned via the API is 500. If you have more than that we will return the 500 most recent conversation parts. {% /admonition %} For AI agent conversation metadata, please note that you need to have the agent enabled in your workspace, which is a paid feature.
GET /conversations/{conversation_id} - Read
Search conversations
You can search for multiple conversations by the value of their attributes in order to fetch exactly which ones you want. To search for conversations, you need to send a POST request to https://api.intercom.io/conversations/search. This will accept a query object in the body which will define your filters in order to search for conversations. {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 20 results per page and maximum is 150. See the pagination section for more details on how to use the startingafter param. {% /admonition %} Nesting & Limitations You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be: - There's a limit of max 2 nested filters - There's a limit of max 15 filters for each AND or OR group Accepted Fields Most keys listed in the conversation model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as createdat accepts a date, the value cannot be a string such as "foorbar"). The source.body field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a "I need support" body - the query should contain a = operator with the value "support" for such conversation to be returned. A query with a = operator and a "need support" value will not yield a result. | Field | Type | | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | | id | String | | createdat | Date (UNIX timestamp) | | updatedat | Date (UNIX timestamp) | | source.type | String Accepted fields are conversation, email, facebook, instagram, phonecall, phoneswitch, push, sms, twitter and whatsapp. | | source.id | String | | source.deliveredas | String | | source.subject | String | | source.body | String | | source.author.id | String | | source.author.type | String | | source.author.name | String | | source.author.email | String | | source.url | String | | contactids | String | | teammateids | String | | adminassigneeid | Integer | | teamassigneeid | Integer | | channelinitiated | String | | open | Boolean | | read | Boolean | | state | String | | waitingsince | Date (UNIX timestamp) | | snoozeduntil | Date (UNIX timestamp) | | tagids | String | | priority | String | | statistics.timetoassignment | Integer | | statistics.timetoadminreply | Integer | | statistics.timetofirstclose | Integer | | statistics.timetolastclose | Integer | | statistics.mediantimetoreply | Integer | | statistics.firstcontactreplyat | Date (UNIX timestamp) | | statistics.firstassignmentat | Date (UNIX timestamp) | | statistics.firstadminreplyat | Date (UNIX timestamp) | | statistics.firstcloseat | Date (UNIX timestamp) | | statistics.lastassignmentat | Date (UNIX timestamp) | | statistics.lastassignmentadminreplyat | Date (UNIX timestamp) | | statistics.lastcontactreplyat | Date (UNIX timestamp) | | statistics.lastadminreplyat | Date (UNIX timestamp) | | statistics.lastcloseat | Date (UNIX timestamp) | | statistics.lastclosedbyid | String | | statistics.countreopens | Integer | | statistics.countassignments | Integer | | statistics.countconversationparts | Integer | | conversationrating.requestedat | Date (UNIX timestamp) | | conversationrating.repliedat | Date (UNIX timestamp) | | conversationrating.score | Integer | | conversationrating.remark | String | | conversationrating.contactid | String | | conversationrating.admind | String | | aiagentparticipated | Boolean | | aiagent.resolutionstate | String | | aiagent.lastanswertype | String | | aiagent.rating | Integer | | aiagent.ratingremark | String | | aiagent.sourcetype | String | | aiagent.sourcetitle | String | Accepted Operators The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string ("="). The operator has to be compatible with the field's type (eg. you cannot search with for a given string value as it's only compatible for integer's and dates). | Operator | Valid Types | Description | | :------- | :----------------------------- | :----------------------------------------------------------- | | = | All | Equals | | != | All | Doesn't Equal | | IN | All | In Shortcut for OR queries Values most be in Array | | NIN | All | Not In Shortcut for OR ! queries Values must be in Array | | | Integer Date (UNIX Timestamp) | Greater (or equal) than | | < | Integer Date (UNIX Timestamp) | Lower (or equal) than | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With |
POST /conversations/search - Read
List handling events
List all pause/resume events for a conversation. These events track when teammates paused or resumed handling a conversation. Requires the readconversations OAuth scope.
GET /conversations/{id}/handling_events - Read
List HITL events
List the human-in-the-loop (HITL) events for a conversation. When Fin is unsure of an answer it can consult a teammate before replying, proposing a draft that the teammate approves, steers with free-text feedback, or takes over. Each consultation is returned as a series of events, oldest first, across every consultation on the conversation. Requires the readconversations OAuth scope, and the caller must be able to access the conversation. Events are only recorded once a consultation has ended, so a consultation still awaiting a teammate does not appear. Which fields appear in data depends on eventtype: | eventtype | data fields | |---|---| | finconsultationstarted | channel, rulethresholdpercent, confidencepercent, sharpask, askrationale, issuesummary, customerquestion | | findraftproposed | draft | | finteammateinputreceived | roundindex, teammateinput, revieweradminid, regenerationoutcome | | findraftrevised | roundindex, reviseddraft, regenerationoutcome | | finconsultationfinished | outcome, approveddrafttype, finaldraft, senttext, revieweradminid, durationseconds, roundscount, payloadtruncated | A consultation always produces a finconsultationstarted and a finconsultationfinished event. findraftproposed appears when Fin proposed a draft. finteammateinputreceived appears once per round of teammate feedback, and findraftrevised once per round where Fin produced a revised draft in response. Notes on interpreting the response: - hitlcycleid identifies the consultation, so it is the same on every event of one consultation. It is not unique per event. A conversation can hold several consultations — a consultation that replaces an outstanding one finishes with an outcome of superseded. - conversationpartid links an event to a conversation part where one exists. It is null in ordinary cases: teammate feedback given through the inbox creates no conversation part, a revised draft has no part of its own, and a consultation that escalated or was superseded sent no reply. - createdat on findraftproposed is approximate. It reports when the consultation started, which is when the draft was proposed. - ruleid, rulename and rulethresholdpercent are recorded when the consultation begins and are not updated afterwards, so a rule that has since been renamed or retuned will not match its current settings. They are null for consultations not triggered by a rule. - revieweradminid identifies the teammate involved in that event: on finteammateinputreceived the teammate who gave the feedback, and on finconsultationfinished the teammate who approved the draft or took over. On a consultation with several rounds these can be different teammates. - roundscount counts every round of teammate feedback the consultation had. Only the ten most recent rounds are retained, so a heavily steered consultation returns fewer finteammateinputreceived events than roundscount. - Redacting a conversation removes this data. Depending on how it was redacted, the conversation either returns no events or returns events whose text fields are all null.
GET /conversations/{id}/hitl_events - Read
List side conversations
List side conversations for a given conversation. Side conversations are internal threads created by teammates from within a conversation. Each side conversation includes its conversation parts (messages). Results are paginated. Requires the readconversations OAuth scope.
GET /conversations/{id}/side_conversations - Read
List all deleted conversation IDs
List all deleted conversation IDs. {% admonition type="warning" name="Pagination" %} You can use pagination to limit the number of results returned. The default is 20 results per page. You can navigate to next pages using the page param. {% /admonition %}
GET /conversations/deleted - Write
Creates a conversation
You can create a conversation that has been initiated by a contact (ie. user or lead). The conversation can be an in-app message only. {% admonition type="info" name="Sending for visitors" %} You can also send a message from a visitor by specifying their id value in the from field, along with a type field value of lead. This visitor will be automatically converted to a contact with a lead role once the conversation is created. {% /admonition %} This will return the Message model that has been created.
POST /conversations - Write
Reply to a conversation
You can reply to a conversation with a message from an admin or on behalf of a contact, or with a note for admins. {% admonition type="warning" name="Bot replies to inbound email" %} By default, bot or Operator replies to an inbound email conversation aren't sent to your customer. The reply is stored as an unnotifiable bot comment, and no seen receipt is generated until an email is actually delivered. To send these replies as outbound emails, reach out to your accounts team to enable the email-reply feature flag for your workspace. {% /admonition %} {% admonition type="info" name="Managing a conversation" %} To close, open, snooze or assign a conversation, use Manage a conversation. {% /admonition %}
POST /conversations/{conversation_id}/reply - Write
Manage a conversation
For managing conversations you can: - Close a conversation - Snooze a conversation to reopen on a future date - Open a conversation which is snoozed or closed - Assign a conversation to an admin and/or team. {% admonition type="info" name="Sending messages" %} To send a comment, note or quick reply, use Reply to a conversation. {% /admonition %}
POST /conversations/{conversation_id}/parts - Write
Attach a contact to a conversation
You can add participants who are contacts to a conversation, on behalf of either another contact or an admin. {% admonition type="warning" name="Contacts without an email" %} If you add a contact via the email parameter and there is no user/lead found on that workspace with he given email, then we will create a new contact with role set to lead. {% /admonition %}
POST /conversations/{conversation_id}/customers - Write
Convert a conversation to a ticket
You can convert a conversation to a ticket.
POST /conversations/{conversation_id}/convert - Destructive
Update a conversation
You can update an existing conversation. {% admonition type="info" name="Replying and other actions" %} If you want to reply to a coveration or take an action such as assign, unassign, open, close or snooze, take a look at the reply and manage endpoints. {% /admonition %} {% admonition type="info" %} This endpoint handles both conversation updates and custom object associations. See update a conversation with an association to a custom object instance in the request/response examples to see the custom object association format. {% /admonition %} {% admonition type="danger" name="Breaking change: duplicate custom attribute names" %} The PUT /conversations/{id} endpoint now returns a 400 INVALIDPARAMETER error when the request includes customattributes and your workspace contains multiple non-archived conversation custom attributes with the same name. Previously, the update would silently apply to a non-deterministic attribute. To resolve, rename or archive the duplicate attribute in your workspace settings, then retry the request. {% /admonition %}
PUT /conversations/{conversation_id} - Destructive
Delete a conversation
{% admonition type="warning" name="Irreversible operation" %} Deleting a conversation is permanent and cannot be reversed. {% /admonition %} You can delete a single conversation. The behavior depends on the retainmetrics parameter: - With retainmetrics=true (default): Deletes the conversation while retaining reporting data. The conversation will still appear in reporting, though some data may be incomplete due to the deletion. - With retainmetrics=false: Deletes the conversation and all associated reporting data. The conversation will be completely removed from both the inbox and all reporting. {% admonition type="info" name="Required scope for retainmetrics=false" %} Using retainmetrics=false requires the deleteconversationsandmetrics OAuth scope. {% /admonition %} For more info, see this help center article.
DELETE /conversations/{conversation_id} - Destructive
Detach a contact from a group conversation
You can remove participants who are contacts from a group conversation, on behalf of an admin. {% admonition type="warning" name="Removing the last participant" %} You cannot remove the last remaining contact from a conversation. {% /admonition %}
DELETE /conversations/{conversation_id}/customers/{contact_id} - Destructive
Redact a conversation part
You can redact a conversation part or the source message of a conversation (as seen in the source object). {% admonition type="info" name="Redacting parts and messages" %} If you are redacting a conversation part, it must have a body. If you are redacting a source message, it must have been created by a contact. We will return a conversationpartnotredactable error if these criteria are not met. {% /admonition %}
POST /conversations/redact - Destructive
Merge a conversation
Merge a secondary (source) conversation into a primary (target) conversation. The secondary conversation is closed and linked to the primary, which becomes the surviving thread. Returns the primary conversation on success. Requires writeconversations OAuth scope. When the secondary is a ticket, writetickets scope is also required.
POST /conversations/{id}/merge
Conversations Attributes
- Read
List all conversation attributes
You can fetch a list of all conversation attributes for your workspace.
GET /conversations/attributes - Read
Get a conversation attribute
Retrieve a single conversation attribute by ID.
GET /conversations/attributes/{id} - Write
Create a conversation attribute
Create a new conversation attribute.
POST /conversations/attributes - Write
Add an option to a list conversation attribute
Add a new option to a list-type conversation attribute. Returns the full attribute with the updated options array.
POST /conversations/attributes/{id}/options - Destructive
Update a conversation attribute
Update an existing conversation attribute.
PUT /conversations/attributes/{id} - Destructive
Delete (archive) a conversation attribute
Archive a conversation attribute (soft delete). The attribute is marked as archived but not permanently deleted.
DELETE /conversations/attributes/{id} - Destructive
Update an option on a list conversation attribute
Update the label of a single option on a list-type conversation attribute. Returns the full attribute with the updated options array.
PUT /conversations/attributes/{id}/options/{option_id} - Destructive
Archive an option on a list conversation attribute
Archive a single option on a list-type conversation attribute (soft delete). The option remains in the response with archived: true. Returns the full attribute with the updated options array.
DELETE /conversations/attributes/{id}/options/{option_id}
Custom Object Instances
- Read
List Custom Object Instances
List instances of a custom object type. Three modes are supported: - No filter — returns all instances for the type. - referencescontactid — returns instances associated with the given contact. - referencesconversationid — returns instances associated with the given conversation. When externalid is provided, returns a single matching instance (not a list). If no instance matches, the response is still 200, with the same body the single-instance endpoint returns for a miss. Requires the readconversations, readuserscompanies, readwritecustomobjectinstances or readwriteusers OAuth scope.
GET /custom_object_instances/{custom_object_type_identifier} - Read
Get Custom Object Instance by ID
Fetch a Custom Object Instance by id. Requires the readconversations, readuserscompanies, readwritecustomobjectinstances or readwriteusers OAuth scope.
GET /custom_object_instances/{custom_object_type_identifier}/{custom_object_instance_id} - Write
Create or Update a Custom Object Instance
Create or update a custom object instance Requires the readwritecustomobjectinstances OAuth scope.
POST /custom_object_instances/{custom_object_type_identifier} - Destructive
Delete a Custom Object Instance by External ID
Delete a single Custom Object instance by externalid. Requires the readwritecustomobjectinstances OAuth scope.
DELETE /custom_object_instances/{custom_object_type_identifier} - Destructive
Delete a Custom Object Instance by ID
Delete a single Custom Object instance using the Intercom defined id. Requires the readwritecustomobjectinstances OAuth scope.
DELETE /custom_object_instances/{custom_object_type_identifier}/{custom_object_instance_id}
Data Attributes
- Read
List all data attributes
You can fetch a list of all data attributes belonging to a workspace for contacts or companies. {% admonition type="warning" %} Conversation attributes are no longer returned by this endpoint. Calling without a model parameter no longer includes them, and model=conversation returns a 422 error. Use GET /conversations/attributes instead. {% /admonition %} Requires the readuserscompanies or readwriteusers OAuth scope.
GET /data_attributes - Write
Create a data attribute
You can create a data attributes for a contact or a company. Requires the writeattributes OAuth scope.
POST /data_attributes - Destructive
Update a data attribute
You can update a data attribute. 🚧 Updating the data type is not possible It is currently a dangerous action to execute changing a data attribute's type via the API. You will need to update the type via the UI instead. You can also send this request with PATCH; it behaves the same as PUT. Requires the writeattributes OAuth scope.
PUT /data_attributes/{data_attribute_id}
Data Connectors
- Read
List all data connectors
Returns a paginated list of all data connectors for the workspace, ordered by most recently updated first. Data connectors allow workflows and AI agents to make HTTP requests to external APIs. OAuth tokens must have the readworkflowconnectorexecutionresult or readwritedataconnectors scope.
GET /data_connectors - Read
Retrieve a data connector
You can retrieve the full detail of a single data connector by its ID. The response includes configuration, data inputs, response fields, and object mappings. OAuth tokens must have the readworkflowconnectorexecutionresult or readwritedataconnectors scope.
GET /data_connectors/{id} - Read
List execution results for a data connector
Retrieve paginated execution logs for a specific data connector. Results from the last hour are returned by default. Use startts and endts to customize the time range. Request/response bodies are excluded by default. Use includebodies=true to include them. OAuth tokens must have the readworkflowconnectorexecutionresult or readwritedataconnectors scope.
GET /data_connectors/{data_connector_id}/execution_results - Read
Retrieve an execution result
Retrieve details for a specific data connector execution result. Includes the request/response bodies and sanitised request URL when they are available. OAuth tokens must have the readworkflowconnectorexecutionresult or readwritedataconnectors scope.
GET /data_connectors/{data_connector_id}/execution_results/{id} - Read
List versions of a data connector
Retrieve the version history of a data connector, newest first. Each entry is a point-in-time snapshot of the connector's configuration, with the status it has today and an optional note. Results are paginated. pages.next is omitted on the last page. A data connector that has never been published returns an empty data list. Requires the readdataconnectorversions or readwritedataconnectorversions OAuth scope.
GET /data_connectors/{id}/versions - Read
Retrieve a version of a data connector
Retrieve a single version of a data connector, including the connector configuration as it was at that version. Requires the readdataconnectorversions or readwritedataconnectorversions OAuth scope.
GET /data_connectors/{id}/versions/{version_id} - Write
Create a data connector
Create a new data connector. The connector is created in draft state. Configure its URL, headers, data inputs, and other settings, then set it to live when ready. OAuth tokens must have the readwritedataconnectors scope.
POST /data_connectors - Write
Update a data connector
Update an existing data connector. Only provided fields are changed. Set state to live or draft to change the connector's state. OAuth tokens must have the readwritedataconnectors scope.
PATCH /data_connectors/{id} - Write
Update the note on a data connector version
Update the note on a data connector version. The note is the only field that can be changed. This does not publish the version or roll the connector back to it. Send an empty string to clear the note. Requires the readwritedataconnectorversions OAuth scope.
PATCH /data_connectors/{id}/versions/{version_id} - Destructive
Delete a data connector
Delete an existing data connector. The connector must be in draft state and must not be in use by any workflows or AI agents. OAuth tokens must have the readwritedataconnectors scope.
DELETE /data_connectors/{id}
Data Events
- Read
List all data events
🚧 Please note that you can only 'list' events that are less than 90 days old. Event counts and summaries will still include your events older than 90 days but you cannot 'list' these events individually if they are older than 90 days The events belonging to a customer can be listed by sending a GET request to https://api.intercom.io/events with a user or lead identifier along with a type parameter. The identifier parameter can be one of userid, email, intercomuserid or anonymousid. The type parameter value must be user or lead. - https://api.intercom.io/events?type=user&userid={userid} - https://api.intercom.io/events?type=user&email={email} - https://api.intercom.io/events?type=user&intercomuserid={id} (this call can be used to list leads) When type is lead, a userid you send is matched against the lead's anonymous id instead. The email parameter value should be url encoded when sending. You can optionally define the result page size as well with the perpage parameter. Requires the readevents or writeevents OAuth scope.
GET /events - Write
Submit a data event
You will need an Access Token that has write permissions to send Events. Once you have a key you can submit events via POST to the Events resource, which is located at https://api.intercom.io/events, or you can send events using one of the client libraries. When working with the HTTP API directly a client should send the event with a Content-Type of application/json. When using the JavaScript API, adding the code to your app makes the Events API available. Once added, you can submit an event using the trackEvent method. This will associate the event with the Lead or currently logged-in user or logged-out visitor/lead and send it to Intercom. The final parameter is a map that can be used to send optional metadata about the event. With the Ruby client you pass a hash describing the event to Intercom::Event.create, or call the trackuser method directly on the current user object (e.g. user.trackevent). NB: For the JSON object types, please note that we do not currently support nested JSON structure. | Type | Description | Example | | :-------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | | String | The value is a JSON String | "source":"desktop" | | Number | The value is a JSON Number | "load": 3.67 | | Date | The key ends with the String date and the value is a Unix timestamp, assumed to be in the UTC timezone. | "contactdate": 1392036272 | | Link | The value is a HTTP or HTTPS URI. | "article": "https://example.org/ab1de.html" | | Rich Link | The value is a JSON object that contains url and value keys. | "article": {"url": "https://example.org/ab1de.html", "value":"the dude abides"} | | Monetary Amount | The value is a JSON object that contains amount and currency keys. The amount key is a positive integer representing the amount in cents. The price in the example to the right denotes €349.99. | "price": {"amount": 34999, "currency": "eur"} | Lead Events When submitting events for Leads, you will need to specify the Lead's id. Metadata behaviour - We currently limit the number of tracked metadata keys to 20 per event name. The limit counts every key ever recorded for that event name, not the keys in a single request, so it is reached cumulatively as you send more events with the same name. Once the quota is reached, we ignore any further keys we receive. The keys that count towards the quota are determined by the order in which they are sent in with the event. - It is not possible to change the metadata keys once the event has been sent. A new event will need to be created with the new keys and you can archive the old one. - There might be up to 24 hrs delay when you send a new metadata for an existing event. Event de-duplication The API may detect and ignore duplicate events. Each event is uniquely identified as a combination of the following data - the Workspace identifier, the Contact external identifier, the Data Event name and the Data Event created time. As a result, it is strongly recommended to send a second granularity Unix timestamp in the createdat field. Duplicated events are responded to using the normal 202 Accepted code - an error is not thrown, however repeat requests will be counted against any rate limit that is in place. HTTP API Responses - Successful responses to submitted events return 202 Accepted with an empty body. - Unauthorised access will be rejected with a 401 Unauthorized or 403 Forbidden response code. - Events sent about users that cannot be found will return a 404 Not Found. - Event lists containing duplicate events will have those duplicates ignored. - Server errors will return a 500 response code and may contain an error message in the body. Requires the writeevents OAuth scope.
POST /events - Write
Create event summaries
Create event summaries for a user. Event summaries are used to track the number of times an event has occurred, the first time it occurred and the last time it occurred. Identify the user with one of id, userid or email. If more than one is sent, id is used first, then userid, then email. Requires the writeevents OAuth scope.
POST /events/summaries
Data Export
- Read
Show content data export
You can view the status of your job by sending a GET request to the URL https://api.intercom.io/export/content/data/{jobidentifier} - the {jobidentifier} is the value returned in the response when you first created the export job. More on it can be seen in the Export Job Model. 🚧 Jobs expire after one week All jobs that have completed processing (and are thus available to download from the provided URL) will have an expiry limit of one week from when the export job was created. After this, the data will no longer be available. A job that failed is returned with a 504 status code and a status of failed. A job left in progress for more than a day is marked failed when you poll it. Requires the exportcontentdata OAuth scope.
GET /export/content/data/{job_identifier} - Read
Download content data export
When a job has a status of complete, and thus a filled downloadurl, you can download your data by hitting that provided URL, formatted like so: https://api.intercom.io/download/content/data/xyz1234. Your exported message data is returned as a ZIP archive containing one CSV file per data group. The response is sent with the header Content-Encoding: zip. 📘 Octet header required You will have to specify the header Accept: application/octet-stream when hitting this endpoint. Requires the exportcontentdata OAuth scope.
GET /download/content/data/{job_identifier} - Write
Create content data export
To create your export job, you need to send a POST request to the export endpoint https://api.intercom.io/export/content/data. This endpoint exports message delivery and engagement data for outbound content (Emails, Posts, Custom Bots, Surveys, Tours, Series, and more). The exported data includes who received each message, when they received it, and how they engaged with it (opens, clicks, replies, completions, dismissals, unsubscribes, and bounces). It does not export raw message or conversation content. The only parameters you need to provide are the range of dates that you want exported. The range cannot be longer than 90 days. 🚧 Limit of two active jobs You can only have two active jobs per workspace. You will receive a HTTP status code of 429 with the message Exceeded rate limit of 2 pending content data export jobs if you attempt to create a third concurrent job. ❗️ Updatedat not included It should be noted that the timeframe only includes messages sent during the time period and not messages that were only updated during this period. For example, if a message was updated yesterday but sent two days ago, you would need to set the createdatafter date before the message was sent to include that in your retrieval job. 📘 Date ranges are inclusive Requesting data for 2018-06-01 until 2018-06-30 will get all data for those days including those specified - e.g. 2018-06-01 00:00:00 until 2018-06-30 23:59:99. Requires the exportcontentdata OAuth scope.
POST /export/content/data - Destructive
Cancel content data export
You can cancel your job. A job that has already reached a terminal state is returned unchanged. Requires the exportcontentdata OAuth scope.
POST /export/cancel/{job_identifier}
Jobs
- Read
Retrieve job status
Retrieve the status of job execution. resourceid and resourceurl are returned only once status is success. While the job is pending or failed both keys are left out of the response rather than returned as null. Requires the readjobs OAuth scope.
GET /jobs/status/{job_id}
Messages
- Read
Retrieve WhatsApp message delivery status
Retrieves the delivery status of a specific WhatsApp message by its message ID. Returns the current status, conversation details, and any error information if the message failed to deliver.
GET /messages/whatsapp/status - Read
Get statuses of all messages sent based on the specified rulesetid
Retrieves statuses of messages sent from the Outbound module. Currently, this API only supports WhatsApp messages. This endpoint returns paginated status events for WhatsApp messages sent via the Outbound module, providing information about delivery state and related message details.
GET /messages/status - Write
Create a message
You can create a message that has been initiated by an admin. The conversation can be either an in-app message, an email or whatsapp. 🚧 Sending for visitors There can be a short delay between when a contact is created and when a contact becomes available to be messaged through the API. A 404 Not Found error will be returned in this case. This will return the Message model that has been created. 🚧 Retrieving Associated Conversations As this is a message, there will be no conversation present until the contact responds. Once they do, you will have to search for a contact's conversations with the id of the message. {% admonition type="warning" name="Messages from contacts" %} from should be an admin. A request with a user or lead as from is not rejected: it creates a conversation initiated by that contact, as the Create a conversation endpoint (POST /conversations) does, and the to, cc and bcc fields are ignored. To create a conversation initiated by a contact, use POST /conversations. {% /admonition %}
POST /messages
News
- Read
List all news items
You can fetch a list of all news items News items are returned newest first, by creation date. Requires the readnewsscope or readwritenewsscope OAuth scope.
GET /news/news_items - Read
Retrieve a news item
You can fetch the details of a single news item. Requires the readnewsscope or readwritenewsscope OAuth scope.
GET /news/news_items/{news_item_id} - Read
List all live newsfeed items
You can fetch a list of all news items that are live on a given newsfeed News items are returned most recently published first. Requires the readnewsscope or readwritenewsscope OAuth scope.
GET /news/newsfeeds/{newsfeed_id}/items - Read
List all newsfeeds
You can fetch a list of all newsfeeds Newsfeeds are returned newest first, by creation date. Requires the readnewsscope or readwritenewsscope OAuth scope.
GET /news/newsfeeds - Read
Retrieve a newsfeed
You can fetch the details of a single newsfeed Requires the readnewsscope or readwritenewsscope OAuth scope.
GET /news/newsfeeds/{newsfeed_id} - Write
Create a news item
You can create a news item Requires the readwritenewsscope OAuth scope.
POST /news/news_items - Destructive
Update a news item
You can update a news item. You can also send this request with PATCH; it behaves the same as PUT. title, body, state, deliversilently and coverimageurl keep their current values when you leave them out. labels and newsfeedassignments do not: leaving either out clears it, so send the full list on every update. Leaving reactions out disables reactions, although the list in the response does not change. Requires the readwritenewsscope OAuth scope.
PUT /news/news_items/{news_item_id} - Destructive
Delete a news item
You can delete a single news item. Requires the readwritenewsscope OAuth scope.
DELETE /news/news_items/{news_item_id}
Segments
- Read
List all segments
You can fetch a list of all segments. Segment names are returned HTML-escaped, for example & as &. Requires the readuserscompanies or writeuserscompanies OAuth scope.
GET /segments - Read
Retrieve a segment
You can fetch the details of a single segment. The segment name is returned HTML-escaped, for example & as &. Requires the readuserscompanies or writeuserscompanies OAuth scope.
GET /segments/{segment_id}
Switch
- Write
Create a phone Switch
You can use the API to deflect phone calls to the Intercom Messenger. Calling this endpoint will send an SMS with a link to the Messenger to the phone number specified. If custom attributes are specified, they will be added to the user or lead's custom data attributes.
POST /phone_call_redirects
Calls
- Read
List all calls
Retrieve a paginated list of calls.
GET /calls - Read
Get a call
Retrieve a single call by id.
GET /calls/{call_id} - Read
Get call recording by call id
Redirects to a signed URL for the call's recording if it exists.
GET /calls/{call_id}/recording - Read
Get call transcript by call id
Returns the transcript for the specified call as a JSON array of turns.
GET /calls/{id}/transcript - Read
List calls with transcripts
Retrieve calls by a list of conversation ids and include transcripts when available. A maximum of 20 conversationids can be provided. If none are provided or more than 20 are provided, a 400 error is returned.
POST /calls/search - Read
Collect Fin Voice call by ID
Retrieve information about a Fin Voice call using the external reference ID.
GET /fin_voice/collect/{id} - Read
Collect Fin Voice call by external ID
Retrieve information about a Fin Voice call using the external call identifier.
GET /fin_voice/external_id/{external_id} - Read
Collect Fin Voice call by phone number
Retrieve information about a Fin Voice call using the phone number. Returns the most recent matched call for the given phone number, ordered by creation date.
GET /fin_voice/phone_number/{phone_number} - Read
Collect Fin Voice calls by conversation ID
Retrieve information about Fin Voice calls associated with a conversation. Returns all matched calls for the given conversation ID. A conversation may have multiple associated calls.
GET /fin_voice/conversation/{conversation_id} - Write
Register a Fin Voice call
Register a Fin Voice call with Intercom. This endpoint creates an external reference that links an external call identifier to an Intercom call and conversation. The call can be from different sources: - AWS Connect (default) - Five9 - Zoom Phone
POST /fin_voice/register
Teams
- Read
List all teams
This will return a list of team objects for the App.
GET /teams - Read
Retrieve a team
You can fetch the details of a single team, containing an array of admins that belong to this team.
GET /teams/{team_id} - Read
Retrieve team metrics
Returns real-time activity metrics for admins in the specified team. For each admin, the response includes counts of open, idle, and snoozed conversations. This endpoint requires the realtimemonitoring feature to be enabled for your workspace.
GET /teams/{team_id}/metrics
Ticket States
- Read
List all ticket states
You can get a list of all ticket states for a workspace.
GET /ticket_states
Ticket Type Attributes
- Write
Create a new attribute for a ticket type
You can create a new attribute for a ticket type.
POST /ticket_types/{ticket_type_id}/attributes - Destructive
Update an existing attribute for a ticket type
You can update an existing attribute for a ticket type.
PUT /ticket_types/{ticket_type_id}/attributes/{attribute_id}
Ticket Types
- Read
List all ticket types
You can get a list of all ticket types for a workspace.
GET /ticket_types - Read
Retrieve a ticket type
You can fetch the details of a single ticket type.
GET /ticket_types/{ticket_type_id} - Write
Create a ticket type
You can create a new ticket type. 📘 Creating ticket types. Every ticket type will be created with two default attributes: defaulttitle and defaultdescription. For the icon propery, use an emoji from Twemoji Cheatsheet
POST /ticket_types - Destructive
Update a ticket type
You can update a ticket type. 📘 Updating a ticket type. For the icon propery, use an emoji from Twemoji Cheatsheet
PUT /ticket_types/{ticket_type_id}
Tickets
- Read
Retrieve a ticket
You can fetch the details of a single ticket.
GET /tickets/{ticket_id} - Read
Search tickets
You can search for multiple tickets by the value of their attributes in order to fetch exactly which ones you want. To search for tickets, you send a POST request to https://api.intercom.io/tickets/search. This will accept a query object in the body which will define your filters. {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 20 results per page and maximum is 150. See the pagination section for more details on how to use the startingafter param. {% /admonition %} Nesting & Limitations You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiples there can be: - There's a limit of max 2 nested filters - There's a limit of max 15 filters for each AND or OR group Accepted Fields Most keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as createdat accepts a date, the value cannot be a string such as "foobar"). Fields not in the table below, such as source.body, are rejected with a 400 error. | Field | Type | | :---------------------------------------- | :--------------------------------------------------------------------------------------- | | id | Integer | | createdat | Date (UNIX timestamp) | | updatedat | Date (UNIX timestamp) | | title | String | | description | String | | category | String | | tickettypeid | Integer | | contactids | String | | adminassigneeid | Integer | | teamassigneeid | Integer | | open | Boolean | | state | String | | snoozeduntil | Date (UNIX timestamp) | | ticketattribute.{id} | String or Boolean or Date (UNIX timestamp) or Float or Integer | {% admonition type="info" name="Searching by Category" %} When searching for tickets by the category field, specific terms must be used instead of the category names: For Customer category tickets, use the term request. For Back-office category tickets, use the term task. For Tracker category tickets, use the term tracker. {% /admonition %} Sorting You can sort the results with a sort object, for example {"field": "createdat", "order": "ascending"}. field must be one of the fields in the table above, other than ticketattribute.{id}, title and description. order is ascending or descending, and any other value is treated as descending. Without sort, results are sorted by updatedat, newest first. Accepted Operators {% admonition type="info" name="Searching based on createdat" %} You may use the = operators to search by createdat. {% /admonition %} The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string ("="). The operator has to be compatible with the field's type (eg. you cannot search with for a given string value as it's only compatible for integer's and dates). | Operator | Valid Types | Description | | :------- | :----------------------------- | :----------------------------------------------------------- | | = | All | Equals | | != | All | Doesn't Equal | | IN | All | In Shortcut for OR queries Values most be in Array | | NIN | All | Not In Shortcut for OR ! queries Values must be in Array | | | Integer Date (UNIX Timestamp) | Greater (or equal) than | | < | Integer Date (UNIX Timestamp) | Lower (or equal) than | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With |
POST /tickets/search - Write
Reply to a ticket
You can reply to a ticket with a message from an admin or on behalf of a contact, or with a note for admins.
POST /tickets/{ticket_id}/reply - Write
Link a conversation to a ticket
Link a conversation to an existing tracker ticket. The conversation can be a regular conversation or one that has been converted into a customer ticket. Use this when related conversations surface after a tracker ticket has already been created. The ticket in the path must be a tracker ticket, and conversationid in the body is the conversation (or customer ticket) to link to it. This returns the linked conversation. A tracker ticket can have up to 2,500 linked conversations; once that limit is reached, further requests return linkedconversationlimitexceeded. Requires the writetickets OAuth scope.
POST /tickets/{ticket_id}/linked_conversations - Write
Create a ticket
You can create a new ticket.
POST /tickets - Write
Enqueue create ticket
Enqueues ticket creation for asynchronous processing, returning if the job was enqueued successfully to be processed. We attempt to perform a best-effort validation on inputs before tasks are enqueued. If the given parameters are incorrect, we won't enqueue the job.
POST /tickets/enqueue - Write
Change ticket type
You can change the type of a ticket. The new ticket type must be in the same category as the current type. Attributes matching by name and type are automatically transferred from the old type; values provided in ticketattributes override transferred values.
POST /tickets/{ticket_id}/change_type - Destructive
Unlink a conversation from a ticket
Unlink a conversation (or converted customer ticket) from a tracker ticket it is currently linked to. The ticket in the path must be a tracker ticket. This returns the conversation that was unlinked. Requires the writetickets OAuth scope.
DELETE /tickets/{ticket_id}/linked_conversations/{id} - Destructive
Update a ticket
You can update a ticket.
PUT /tickets/{ticket_id} - Destructive
Delete a ticket
{% admonition type="warning" name="Irreversible operation" %} Deleting a ticket is permanent and cannot be reversed. {% /admonition %} Deleting a ticket permanently removes it from the inbox. All sensitive data is deleted, including admin and user replies, ticket attributes, uploads, and related content. The ticket will still appear in reporting, though some data may be incomplete due to the deletion.
DELETE /tickets/{ticket_id}
Visitors
- Read
Retrieve a visitor with User ID
You can fetch the details of a single visitor. Requires the readsingleuser, readuserscompanies or readwriteusers OAuth scope.
GET /visitors - Destructive
Update a visitor
Sending a PUT request to /visitors will result in an update of an existing Visitor. Option 1. You can update a visitor by passing in the userid of the visitor in the Request body. Option 2. You can update a visitor by passing in the id of the visitor in the Request body. Sending an email promotes the visitor to a lead. When that happens the response is a contact object with a role of lead, not a visitor object. Requires the readwriteusers or writeuserscompanies OAuth scope.
PUT /visitors - Destructive
Convert a visitor
You can merge a Visitor to a Contact of role type lead or user. 📘 What happens upon a visitor being converted? If the User exists, then the Visitor will be merged into it, the Visitor deleted and the User returned. If the User does not exist, the Visitor will be converted to a User, with the User identifiers replacing it's Visitor identifiers. Identify the visitor with visitor.id or visitor.userid. The user object is required when type is user, and is not read when type is lead. Requires the readwriteusers or writeuserscompanies OAuth scope.
POST /visitors/convert
Brands
- Read
List all brands
Retrieves all brands for the workspace, including the default brand. The default brand id always matches the workspace id. Requires the readbrands OAuth scope.
GET /brands - Read
Retrieve a brand
Fetches a specific brand by its unique identifier Requires the readbrands OAuth scope.
GET /brands/{id}
Emails
- Read
List all email settings
Lists all sender email address settings for the workspace
GET /emails - Read
Retrieve an email setting
Fetches a specific email setting by its unique identifier
GET /emails/{id}
Workflows
- Read
Export a workflow
Export a workflow configuration by its ID. This endpoint returns the complete workflow definition including its steps, targeting rules, and attributes. The id in the path is the workflow's ruleset ID, the number at the end of the workflow's URL in Intercom (https://app.intercom.com/a/apps/ /automation/workflows/ ). The workflow.id in the response is a different ID, so don't pass it back as id. This endpoint is designed for EU Data Act compliance, allowing customers to export their workflow configurations.
GET /export/workflows/{id}
No operations match.
Get started
- Open Space settings → Connections and search for Intercom.
- Connect your account and add the connection to the Space.
- Ask for what you need in any thread in that Space.
See How connections work for access and permissions, or browse all integrations.