Intercom

Intercom API

The intercom API reference.

Communication#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

The intercom API reference.

Endpoints 154

Admins

  • GETIdentify an admin/meYou can view the currently authorised admin along with the embedded app object (a "workspace" in legacy terminology). > 🚧 Single Sign On > > If you are…
  • PUTSet an admin to away/admins/:admin_id/awayYou can set an Admin as away for the Inbox.
  • GETList all activity logs/admins/activity_logs?created_at_after=1677253093&created_at_before=1677861493You can get a log of activities by all admins in an app.
  • GETList all admins/admins?display_avatar=trueYou can fetch a list of admins for a given workspace.
  • GETRetrieve an admin/admins/:admin_idYou can retrieve the details of a single admin.

AI Content

  • GETList content import sources/ai/content_import_sourcesYou can retrieve a list of all content import sources for a workspace.
  • POSTCreate a content import source/ai/content_import_sourcesYou can create a new content import source by sending a POST request to this endpoint.
  • GETRetrieve a content import source/ai/content_import_sources/:source_id
  • PUTUpdate a content import source/ai/content_import_sources/:source_idYou can update an existing content import source.
  • DELETEDelete a content import source/ai/content_import_sources/:source_idYou 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.
  • GETList external pages/ai/external_pagesYou can retrieve a list of all external pages for a workspace.
  • POSTCreate an external page (or update an external page by external ID)/ai/external_pagesYou can create a new external page by sending a POST request to this endpoint. If an external page already exists with the specified source_id and…
  • GETRetrieve an external page/ai/external_pages/:page_idYou can retrieve an external page.
  • PUTUpdate an external page/ai/external_pages/:page_idYou can update an existing external page (if it was created via the API).
  • DELETEDelete an external page/ai/external_pages/:page_idSending a DELETE request for an external page will remove it from the content library UI and from being used for AI answers.

Articles

  • GETList all articles/articlesYou 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…
  • POSTCreate an article/articlesYou can create a new article by making a POST request to https://api.intercom.io/articles. > 📘 Tags cannot be managed via the Articles API > > Article tags…
  • GETRetrieve an article/articles/:article_idYou can fetch the details of a single article by making a GET request to https://api.intercom.io/articles/<id>.
  • PUTUpdate an article/articles/:article_idYou can update the details of a single article by making a PUT request to https://api.intercom.io/articles/<id>. > 📘 Tags cannot be managed via the Articles…
  • DELETEDelete an article/articles/:article_idYou can delete a single article by making a DELETE request to https://api.intercom.io/articles/<id>.
  • GETSearch for articles/articles/search?phrase=Getting started&state=published&help_center_id=123&highlight=falseYou can search for articles by making a GET request to https://api.intercom.io/articles/search.

Away Status Reasons

  • GETList all away status reasons/away_status_reasonsReturns a list of all away status reasons configured for the workspace, including deleted ones.

Calls

  • GETList all calls/calls?page=1&per_page=25Retrieve a paginated list of calls.
  • GETGet a call/calls/:call_idRetrieve a single call by id.
  • GETGet call recording by call id/calls/:call_id/recordingRedirects to a signed URL for the call's recording if it exists.
  • GETGet call transcript by call id/calls/:call_id/transcriptReturns the transcript for the specified call as a downloadable text file.
  • POSTList calls with transcripts/calls/searchRetrieve calls by a list of conversation ids and include transcripts when available. A maximum of 20 conversation_ids can be provided. If none are provided or…

Companies

  • GETRetrieve companies/companies?name=my company&company_id=12345&tag_id=678910&segment_id=98765&page=1&per_page=15You can fetch a single company by passing in company_id or name. https://api.intercom.io/companies?name={name}…
  • POSTCreate or Update a company/companiesYou 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…
  • GETRetrieve a company by ID/companies/:company_idYou can fetch a single company.
  • PUTUpdate a company/companies/:company_idYou can update a single company using the Intercom provisioned id. {% admonition type="warning" name="Using company_id" %} When updating a company it is not…
  • DELETEDelete a company/companies/:company_idDelete a single company. The company record is kept in your workspace, but all contacts are detached. The contacts themselves are not deleted. Detaching…
  • GETList attached contacts/companies/:company_id/contactsYou can fetch a list of all contacts that belong to a company.
  • GETList attached segments for companies/companies/:company_id/segmentsYou can fetch a list of all segments that belong to a company.
  • POSTList all companies/companies/list?page=1&per_page=15&order=descYou can list companies. The company list is sorted by the last_request_at field and by default is ordered descending, most recently requested first. Note that…
  • GETScroll over all companies/companies/scroll?scroll_param=stringThe list all companies functionality does not work well for huge datasets, and can result in errors and performance problems when paging deeply. The Scroll…
  • POSTAttach a Contact to a Company/contacts/:contact_id/companiesYou can attach a company to a single contact.
  • DELETEDetach a contact from a company/contacts/:contact_id/companies/:company_idYou can detach a company from a single contact.

Contacts

  • GETList attached companies for contact/contacts/:contact_id/companiesYou can fetch a list of companies that are associated to a contact.
  • GETList attached segments for contact/contacts/:contact_id/segmentsYou can fetch a list of segments that are associated to a contact.
  • GETList subscriptions for a contact/contacts/:contact_id/subscriptionsYou 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,…
  • GETList tags attached to a contact/contacts/:contact_id/tagsYou can fetch a list of all tags that are attached to a specific contact.
  • GETGet a contact/contacts/:contact_idYou can fetch the details of a single contact. {% admonition type="warning" name="Merged contacts" %} If a contact has been merged into another contact via…
  • PUTUpdate a contact/contacts/:contact_idYou can update an existing contact (ie. user or lead). {% admonition type="info" %} This endpoint handles both contact updates and custom object associations.…
  • DELETEDelete a contact/contacts/:contact_idYou can delete a single contact.
  • POSTMerge a lead and a user/contacts/mergeYou 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…
  • POSTSearch contacts/contacts/searchYou 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…
  • GETList all contacts/contactsYou can fetch a list of all contacts (ie. users or leads) in your workspace. {% admonition type="info" name="Merged contacts" %} Contacts that have been…
  • POSTCreate contact/contactsYou can create a new contact (ie. user or lead).
  • GETGet a contact by External ID/contacts/find_by_external_id/:external_idYou can fetch the details of a single contact by external ID. Note that this endpoint only supports users and not leads.
  • POSTArchive contact/contacts/:contact_id/archiveYou can archive a single contact.
  • POSTUnarchive contact/contacts/:contact_id/unarchiveYou can unarchive a single contact.
  • POSTBlock contact/contacts/:contact_id/blockBlock a single contact.<br>Note: conversations of the contact will also be archived during the process.<br>More details in FAQ How do I block Inbox spam?

Conversations

  • GETList all conversations/conversations?per_page=20&starting_after=stringYou 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…
  • POSTCreates a conversation/conversationsYou 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…
  • GETRetrieve a conversation/conversations/:conversation_id?display_as=plaintext&include_translations=trueYou can fetch the details of a single conversation. This will return a single Conversation model with all its conversation parts. {% admonition type="warning"…
  • PUTUpdate a conversation/conversations/:conversation_id?display_as=plaintextYou 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…
  • DELETEDelete a conversation/conversations/:conversation_id{% admonition type="warning" name="Irreversible operation" %} Deleting a conversation is permanent and cannot be reversed. {% /admonition %} Deleting a…
  • POSTSearch conversations/conversations/searchYou 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…
  • POSTReply to a conversation/conversations/:conversation_id/replyYou 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…
  • POSTManage a conversation/conversations/:conversation_id/partsFor managing conversations you can: Close a conversation Snooze a conversation to reopen on a future date Open a conversation which is snoozed or closed…
  • POSTAttach a contact to a conversation/conversations/:conversation_id/customersYou can add participants who are contacts to a conversation, on behalf of either another contact or an admin. {% admonition type="warning" name="Contacts…
  • DELETEDetach a contact from a group conversation/conversations/:conversation_id/customers/:contact_idYou can remove participants who are contacts from a group conversation, on behalf of an admin. {% admonition type="warning" name="Removing the last…
  • POSTRedact a conversation part/conversations/redactYou 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…
  • POSTConvert a conversation to a ticket/conversations/:conversation_id/convertYou can convert a conversation to a ticket.

Custom Object Instances

  • GETGet Custom Object Instance by External ID/custom_object_instances/:custom_object_type_identifier?external_id=stringFetch a Custom Object Instance by external_id.
  • POSTCreate or Update a Custom Object Instance/custom_object_instances/:custom_object_type_identifierCreate or update a custom object instance
  • DELETEDelete a Custom Object Instance by External ID/custom_object_instances/:custom_object_type_identifier?external_id=stringDelete a single Custom Object instance by external_id.
  • GETGet Custom Object Instance by ID/custom_object_instances/:custom_object_type_identifier/:custom_object_instance_idFetch a Custom Object Instance by id.
  • DELETEDelete a Custom Object Instance by ID/custom_object_instances/:custom_object_type_identifier/:custom_object_instance_idDelete a single Custom Object instance using the Intercom defined id.

Data Attributes

  • GETList all data attributes/data_attributes?model=company&include_archived=falseYou can fetch a list of all data attributes belonging to a workspace for contacts, companies or conversations.
  • POSTCreate a data attribute/data_attributesYou can create a data attributes for a contact or a company.
  • PUTUpdate a data attribute/data_attributes/:data_attribute_idYou 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…

Data Events

  • GETList all data events/events?filter={"user_id":"string"}&type=string&summary=true> 🚧 > > 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…
  • POSTSubmit a data event/eventsYou 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…
  • POSTCreate event summaries/events/summariesCreate 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…

Data Export

  • POSTCreate content data export/export/content/dataTo 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…
  • GETShow content data export/export/content/data/:job_identifierYou can view the status of your job by sending a GET request to the URL https://api.intercom.io/export/content/data/{job_identifier} - the {job_identifier} is…
  • POSTCancel content data export/export/cancel/:job_identifierYou can cancel your job
  • GETDownload content data export/download/content/data/:job_identifierWhen a job has a status of complete, and thus a filled download_url, you can download your data by hitting that provided URL, formatted like so:…

Fin Agent

  • POSTStart a conversation with Fin/fin/startInitialize 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…
  • POSTReply to Fin/fin/replyOnce Fin has returned a response to a user's message, its status will be awaiting_user_reply. If a user replies, use this endpoint to send this response to…
  • POSTSubmit a CSAT rating/fin/csatRecord 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…
  • POSTDiscover Fin's capabilities/fin/capabilitiesReturn 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…
  • POSTAsk Fin/fin/askAsk Fin a single, self-contained question and receive one informational answer. Unlike a conversation, /fin/ask is non-conversational: Fin will not ask…
  • POSTRun a Fin procedure/fin/procedures/:procedure_id/runDeterministically run a specific procedure on a new conversation. Calling this endpoint guarantees that the named procedure runs — there is no…
  • POSTEscalate to a human/fin/escalateHand a conversation off to a human teammate. If you use the Intercom Helpdesk, the handoff lands in your team inbox. Provide either conversation_id or user:…

Help Center

  • GETList all collections/help_center/collectionsYou can fetch a list of all collections by making a GET request to https://api.intercom.io/help_center/collections. Collections will be returned in descending…
  • POSTCreate a collection/help_center/collectionsYou can create a new collection by making a POST request to https://api.intercom.io/help_center/collections.
  • GETRetrieve a collection/help_center/collections/:collection_idYou can fetch the details of a single collection by making a GET request to https://api.intercom.io/help_center/collections/<id>.
  • PUTUpdate a collection/help_center/collections/:collection_idYou can update the details of a single collection by making a PUT request to https://api.intercom.io/collections/<id>.
  • DELETEDelete a collection/help_center/collections/:collection_idYou can delete a single collection by making a DELETE request to https://api.intercom.io/collections/<id>.
  • GETRetrieve a Help Center/help_center/help_centers/:help_center_idYou can fetch the details of a single Help Center by making a GET request to https://api.intercom.io/help_center/help_center/<id>.
  • GETList all Help Centers/help_center/help_centersYou can list all Help Centers by making a GET request to https://api.intercom.io/help_center/help_centers.

Internal Articles

  • GETList all articles/internal_articlesYou can fetch a list of all internal articles by making a GET request to https://api.intercom.io/internal_articles.
  • POSTCreate an internal article/internal_articlesYou can create a new internal article by making a POST request to https://api.intercom.io/internal_articles.
  • GETRetrieve an internal article/internal_articles/:internal_article_idYou can fetch the details of a single internal article by making a GET request to https://api.intercom.io/internal_articles/<id>.
  • PUTUpdate an internal article/internal_articles/:internal_article_idYou can update the details of a single internal article by making a PUT request to https://api.intercom.io/internal_articles/<id>.
  • DELETEDelete an internal article/internal_articles/:internal_article_idYou can delete a single internal article by making a DELETE request to https://api.intercom.io/internal_articles/<id>.
  • GETSearch for internal articles/internal_articles/search?folder_id=123You can search for internal articles by making a GET request to https://api.intercom.io/internal_articles/search.

IP Allowlist

  • GETGet IP allowlist settings/ip_allowlistRetrieve the current IP allowlist configuration for the workspace.
  • PUTUpdate IP allowlist settings/ip_allowlistUpdate the IP allowlist configuration for the workspace. {% admonition type="warning" name="Lockout Protection" %} The API will reject updates that would lock…

Jobs

  • GETRetrieve job status/jobs/status/:job_idRetrieve the status of job execution.

Messages

  • POSTCreate a message/messagesYou can create a message that has been initiated by an admin. The conversation can be either an in-app message or an email. > 🚧 Sending for visitors > > There…

News

  • GETList all news items/news/news_itemsYou can fetch a list of all news items
  • POSTCreate a news item/news/news_itemsYou can create a news item
  • GETRetrieve a news item/news/news_items/:news_item_idYou can fetch the details of a single news item.
  • PUTUpdate a news item/news/news_items/:news_item_id
  • DELETEDelete a news item/news/news_items/:news_item_idYou can delete a single news item.
  • GETList all live newsfeed items/news/newsfeeds/:newsfeed_id/itemsYou can fetch a list of all news items that are live on a given newsfeed
  • GETList all newsfeeds/news/newsfeedsYou can fetch a list of all newsfeeds
  • GETRetrieve a newsfeed/news/newsfeeds/:newsfeed_idYou can fetch the details of a single newsfeed

Notes

  • GETList all notes/contacts/:contact_id/notesYou can fetch a list of notes that are associated to a contact.
  • POSTCreate a note/contacts/:contact_id/notesYou can add a note to a single contact.
  • GETRetrieve a note/notes/:note_idYou can fetch the details of a single note.

Reporting Data Export

  • POSTEnqueue a new reporting data export job/export/reporting_data/enqueue
  • GETGet export job status/export/reporting_data/:job_identifier?app_id=string&client_id=string&job_identifier=string
  • GETList available datasets and attributes/export/reporting_data/get_datasets
  • GETDownload completed export job data/download/reporting_data/:job_identifier?app_id=string&job_identifier=stringDownload the data from a completed reporting data export job. > Octet header required > > You will have to specify the header Accept: application/octet-stream…

Segments

  • GETList all segments/segments?include_count=trueYou can fetch a list of all segments.
  • GETRetrieve a segment/segments/:segment_idYou can fetch the details of a single segment.

Subscription Types

  • POSTAdd subscription to a contact/contacts/:contact_id/subscriptionsYou 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:…
  • DELETERemove subscription from a contact/contacts/:contact_id/subscriptions/:subscription_idYou 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.
  • GETList subscription types/subscription_typesYou can list all subscription types. A list of subscription type objects will be returned.

Switch

  • POSTCreate a phone Switch/phone_call_redirectsYou 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…

Tags

  • POSTAdd tag to a contact/contacts/:contact_id/tagsYou can tag a specific contact. This will return a tag object for the tag that was added to the contact.
  • DELETERemove tag from a contact/contacts/:contact_id/tags/:tag_idYou can remove tag from a specific contact. This will return a tag object for the tag that was removed from the contact.
  • POSTAdd tag to a conversation/conversations/:conversation_id/tagsYou can tag a specific conversation. This will return a tag object for the tag that was added to the conversation.
  • DELETERemove tag from a conversation/conversations/:conversation_id/tags/:tag_idYou can remove tag from a specific conversation. This will return a tag object for the tag that was removed from the conversation.
  • GETList all tags/tagsYou can fetch a list of all tags for a given workspace.
  • POSTCreate or update a tag, Tag or untag companies, Tag contacts/tagsYou 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…
  • GETFind a specific tag/tags/:tag_idYou can fetch the details of tags that are on the workspace by their id. This will return a tag object.
  • DELETEDelete tag/tags/:tag_idYou can delete the details of tags that are on the workspace by passing in the id.
  • POSTAdd tag to a ticket/tickets/:ticket_id/tagsYou can tag a specific ticket. This will return a tag object for the tag that was added to the ticket.
  • DELETERemove tag from a ticket/tickets/:ticket_id/tags/:tag_idYou can remove tag from a specific ticket. This will return a tag object for the tag that was removed from the ticket.

Teams

  • GETList all teams/teamsThis will return a list of team objects for the App.
  • GETRetrieve a team/teams/:team_idYou can fetch the details of a single team, containing an array of admins that belong to this team.

Ticket States

  • GETList all ticket states/ticket_statesYou can get a list of all ticket states for a workspace.

Ticket Type Attributes

  • POSTCreate a new attribute for a ticket type/ticket_types/:ticket_type_id/attributesYou can create a new attribute for a ticket type.
  • PUTUpdate an existing attribute for a ticket type/ticket_types/:ticket_type_id/attributes/:attribute_idYou can update an existing attribute for a ticket type.

Ticket Types

  • GETList all ticket types/ticket_typesYou can get a list of all ticket types for a workspace.
  • POSTCreate a ticket type/ticket_typesYou can create a new ticket type. > 📘 Creating ticket types. > > Every ticket type will be created with two default attributes: _default_title_ and…
  • GETRetrieve a ticket type/ticket_types/:ticket_type_idYou can fetch the details of a single ticket type.
  • PUTUpdate a ticket type/ticket_types/:ticket_type_idYou can update a ticket type. > 📘 Updating a ticket type. > > For the icon propery, use an emoji from Twemoji Cheatsheet

Tickets

  • POSTReply to a ticket/tickets/:ticket_id/replyYou can reply to a ticket with a message from an admin or on behalf of a contact, or with a note for admins.
  • POSTCreate a ticket/ticketsYou can create a new ticket.
  • POSTEnqueue create ticket/tickets/enqueueEnqueues ticket creation for asynchronous processing, returning if the job was enqueued successfully to be processed. We attempt to perform a best-effort…
  • GETRetrieve a ticket/tickets/:ticket_idYou can fetch the details of a single ticket.
  • PUTUpdate a ticket/tickets/:ticket_idYou can update a ticket.
  • DELETEDelete a ticket/tickets/:ticket_id{% admonition type="warning" name="Irreversible operation" %} Deleting a ticket is permanent and cannot be reversed. {% /admonition %} Deleting a ticket…
  • POSTSearch tickets/tickets/searchYou 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…

Visitors

  • GETRetrieve a visitor with User ID/visitors?user_id=stringYou can fetch the details of a single visitor.
  • PUTUpdate a visitor/visitorsSending 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 user_id of the…
  • POSTConvert a visitor/visitors/convertYou 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…

API details

Base URL
https://api.intercom.io
https://api.eu.intercom.io
https://api.au.intercom.io
Authentication
A bearer token in the Authorization header
Operations
154 operations on 110 pathsGET 67POST 52DELETE 19PUT 16
Main resources
Contacts 24Conversations 14Companies 12Tags 11AI Content 10Tickets 9News 8Custom Object Instances 7Fin Agent 7Help Center 7
Response formats
application/json text/plain
Description format
OpenAPI 3.0.1, API version 2.14

How to test the Intercom API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Intercom API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Identify an admin” (GET /me), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Intercom API?

The intercom API reference. It is listed under Communication and has 154 endpoints.

Who publishes the Intercom API?

It is listed from Intercom's public API description (an OpenAPI document), not published by Intercom on Swastik Codes. Anyone who controls intercom.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Intercom API?

Its description lists 3 base URLs: https://api.intercom.io, https://api.eu.intercom.io, https://api.au.intercom.io. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Intercom API?

With A bearer token in the Authorization header.

How many endpoints does the Intercom API have?

154 operations on 110 paths (67 GET, 52 POST, 19 DELETE, 16 PUT). The largest groups are Contacts, Conversations, Companies, Tags.

Is forking the Intercom API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.