Skip to content
Changelog

Report a bug

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 &amp;. 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 &amp;. 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}

Get started

  1. Open Space settings → Connections and search for Intercom.
  2. Connect your account and add the connection to the Space.
  3. Ask for what you need in any thread in that Space.

See How connections work for access and permissions, or browse all integrations.