The intercom API reference.
Intercom API (Unstable)
Download OpenAPI description
Overview
URL
License
Languages
Servers
The production API server
https://api.intercom.io/
The european API server
https://api.eu.intercom.io/
The australian API server
https://api.au.intercom.io/
AI Content
With the AI Content APIs, you can create and manage External Pages and Content Import Sources for your Fin Content Library.
External Pages are pages that you want Fin to be able to answer questions about. The API for External Pages is a great way to ingest into your Fin Content Library pages that are not publicly accessible and hence can't be crawled by Intercom.
Content Import Sources are the sources of those pages, and they are used to determine the default audience for the pages (configured via the UI). You should create a Content Import Source for each source of External Pages that you want to ingest into your Fin Content Library.
You can then iterate through the content from that source via its API and POST it to the External Pages endpoint. That endpoint has an external_id parameter which allows you to specify the identifier from the source. The endpoint will then either create a new External Page or update an existing one as appropriate.",
Operations
Article
The Articles API is a central place to gather all information and take actions on your articles. Articles can live within collections and sections, or alternatively they can stand alone.
The title of the article. For multilingual articles, this will be the title of the default language's content.
Example: "Default language title"
The description of the article. For multilingual articles, this will be the description of the default language's content.
Example: "Default language description"
The body of the article in HTML. For multilingual articles, this will be the body of the default language's content.
Example: "Default language body in html"
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
Example: "5017691"
Whether the article is published or is a draft. For multilingual articles, this will be the state of the default language's content.
Default "draft"
Enum"published""draft"
Example: "published"
The time when the article was created. For multilingual articles, this will be the timestamp of creation of the default language's content in seconds.
Example: 1672928359
The time when the article was last updated. For multilingual articles, this will be the timestamp of last update of the default language's content in seconds.
Example: 1672928610
The URL of the article. For multilingual articles, this will be the URL of the default language's content.
Example: "http://intercom.test/help/en/articles/3-default-language"
The id of the article's parent collection or section. An article without this field stands alone.
Example: "125685"
The ids of the article's parent collections or sections. An article without this field stands alone.
Example: [18,19]
The type of parent, which can either be a collection or section.
Example: "collection"
The default locale of the help center. This field is only returned for multilingual help centers.
Example: "en"
{ "statistics": { "type": "article_statistics", "views": 10, "conversions": 0, "reactions": 10, "happy_reaction_percentage": 40, "neutral_reaction_percentage": 40, "sad_reaction_percentage": 20 }, "type": "article", "id": "6871119", "workspace_id": "hfi1bx4l", "title": "Default language title", "description": "Default language description", "body": "Default language body in html", "author_id": "5017691", "state": "published", "created_at": 1672928359, "updated_at": 1672928610, "url": "http://intercom.test/help/en/articles/3-default-language", "parent_id": "125685", "parent_ids": [ 18, 19 ], "parent_type": "collection", "default_locale": "en", "translated_content": { "type": "article_translated_content", "ar": { … }, "bg": { … }, "bs": { … }, "ca": { … }, "cs": { … }, "da": { … }, "de": { … }, "el": { … }, "en": { … }, "es": { … }, "et": { … }, "fi": { … }, "fr": { … }, "he": { … }, "hr": { … }, "hu": { … }, "id": { … }, "it": { … }, "ja": { … }, "ko": { … }, "lt": { … }, "lv": { … }, "mn": { … }, "nb": { … }, "nl": { … }, "pl": { … }, "pt": { … }, "ro": { … }, "ru": { … }, "sl": { … }, "sr": { … }, "sv": { … }, "tr": { … }, "vi": { … }, "pt-BR": { … }, "zh-CN": { … }, "zh-TW": { … } } }
Internal Article
The Internal Articles API is a central place to gather all information and take actions on your internal articles.
The type of object - internal_article.
Default "internal_article"
Value"internal_article"
Example: "internal_article"
{ "type": "internal_article", "id": "6871119", "title": "string", "body": "Default language body in html", "owner_id": "5017691", "author_id": "5017691", "created_at": 1672928359, "updated_at": 1672928610, "locale": "en" }
Articles
The data returned about your articles when you list them.
The title of the article. For multilingual articles, this will be the title of the default language's content.
Example: "Default language title"
The description of the article. For multilingual articles, this will be the description of the default language's content.
Example: "Default language description"
The body of the article in HTML. For multilingual articles, this will be the body of the default language's content.
Example: "Default language body in html"
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
Example: "5017691"
Whether the article is published or is a draft. For multilingual articles, this will be the state of the default language's content.
Default "draft"
Enum"published""draft"
Example: "published"
The time when the article was created. For multilingual articles, this will be the timestamp of creation of the default language's content in seconds.
Example: 1672928359
The time when the article was last updated. For multilingual articles, this will be the timestamp of last update of the default language's content in seconds.
Example: 1672928610
The URL of the article. For multilingual articles, this will be the URL of the default language's content.
Example: "http://intercom.test/help/en/articles/3-default-language"
The id of the article's parent collection or section. An article without this field stands alone.
Example: "125685"
The ids of the article's parent collections or sections. An article without this field stands alone.
Example: [18,19]
The type of parent, which can either be a collection or section.
Example: "collection"
The default locale of the help center. This field is only returned for multilingual help centers.
Example: "en"
{ "type": "article", "id": "6871119", "workspace_id": "hfi1bx4l", "title": "Default language title", "description": "Default language description", "body": "Default language body in html", "author_id": "5017691", "state": "published", "created_at": 1672928359, "updated_at": 1672928610, "url": "http://intercom.test/help/en/articles/3-default-language", "parent_id": "125685", "parent_ids": [ 18, 19 ], "parent_type": "collection", "default_locale": "en", "translated_content": { "type": "article_translated_content", "ar": { … }, "bg": { … }, "bs": { … }, "ca": { … }, "cs": { … }, "da": { … }, "de": { … }, "el": { … }, "en": { … }, "es": { … }, "et": { … }, "fi": { … }, "fr": { … }, "he": { … }, "hr": { … }, "hu": { … }, "id": { … }, "it": { … }, "ja": { … }, "ko": { … }, "lt": { … }, "lv": { … }, "mn": { … }, "nb": { … }, "nl": { … }, "pl": { … }, "pt": { … }, "ro": { … }, "ru": { … }, "sl": { … }, "sr": { … }, "sv": { … }, "tr": { … }, "vi": { … }, "pt-BR": { … }, "zh-CN": { … }, "zh-TW": { … } } }
Article Search Response
The results of an Article search
Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.
{ "type": "list", "total_count": 5, "data": { "articles": [ … ], "highlights": [ … ] }, "pages": { "type": "pages", "page": 1, "next": { … }, "per_page": 2, "total_pages": 13 } }
Request
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
updated_atattribute. This means if you need to iterate through results then we'll show the most recently updated articles first.
Security
bearerAuth
- The production API server
https://api.intercom.io/articles
- The european API server
https://api.eu.intercom.io/articles
- The australian API server
https://api.au.intercom.io/articles
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X GET \
https://api.intercom.io/articles \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'Response
application/json
{ "type": "list", "pages": { "type": "pages", "page": 1, "per_page": 25, "total_pages": 1 }, "total_count": 1, "data": [ { … } ] }
Bodyapplication/json
The title of the article.For multilingual articles, this will be the title of the default language's content.
Example: "Thanks for everything"
The description of the article. For multilingual articles, this will be the description of the default language's content.
Example: "Description of the Article"
The content of the article. For multilingual articles, this will be the body of the default language's content.
Example: "<p>This is the body in html</p>"
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
Example: 1295
Whether the article will be published or will be a draft. Defaults to draft. For multilingual articles, this will be the state of the default language's content.
Enum"published""draft"
Example: "draft"
The id of the article's parent collection or section. An article without this field stands alone.
Example: 18
The type of parent, which can either be a collection or section.
Example: "collection"
- The production API server
https://api.intercom.io/articles
- The european API server
https://api.eu.intercom.io/articles
- The australian API server
https://api.au.intercom.io/articles
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X POST \
https://api.intercom.io/articles \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"title": "Thanks for everything",
"description": "Description of the Article",
"body": "Body of the Article",
"author_id": 991267497,
"state": "published",
"parent_id": 145,
"parent_type": "collection",
"translated_content": {
"fr": {
"title": "Merci pour tout",
"description": "Description de l'\''article",
"body": "Corps de l'\''article",
"author_id": 991267497,
"state": "published"
}
}
}'article created
The title of the article. For multilingual articles, this will be the title of the default language's content.
Example: "Default language title"
The description of the article. For multilingual articles, this will be the description of the default language's content.
Example: "Default language description"
The body of the article in HTML. For multilingual articles, this will be the body of the default language's content.
Example: "Default language body in html"
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
Example: "5017691"
Whether the article is published or is a draft. For multilingual articles, this will be the state of the default language's content.
Default "draft"
Enum"published""draft"
Example: "published"
The time when the article was created. For multilingual articles, this will be the timestamp of creation of the default language's content in seconds.
Example: 1672928359
The time when the article was last updated. For multilingual articles, this will be the timestamp of last update of the default language's content in seconds.
Example: 1672928610
The URL of the article. For multilingual articles, this will be the URL of the default language's content.
Example: "http://intercom.test/help/en/articles/3-default-language"
The id of the article's parent collection or section. An article without this field stands alone.
Example: "125685"
The ids of the article's parent collections or sections. An article without this field stands alone.
Example: [18,19]
The type of parent, which can either be a collection or section.
Example: "collection"
The default locale of the help center. This field is only returned for multilingual help centers.
Example: "en"
Response
application/json
{ "id": "42", "type": "article", "workspace_id": "this_is_an_id68_that_should_be_at_least_4", "parent_id": 145, "parent_type": "collection", "parent_ids": [], "statistics": { "type": "article_statistics", "views": 0, "conversations": 0, "reactions": 0, "happy_reaction_percentage": 0, "neutral_reaction_percentage": 0, "sad_reaction_percentage": 0 }, "tags": { "type": "tag.list", "tags": [] }, "title": "Thanks for everything", "description": "Description of the Article", "body": "<p class=\"no-margin\">Body of the Article</p>", "author_id": 991267497, "state": "published", "created_at": 1734537288, "updated_at": 1734537288, "url": "http://help-center.test/myapp-68/en/articles/42-thanks-for-everything" }
- The production API server
https://api.intercom.io/articles/{id}
- The european API server
https://api.eu.intercom.io/articles/{id}
- The australian API server
https://api.au.intercom.io/articles/{id}
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X GET \
https://api.intercom.io/articles/123 \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'Article found
The title of the article. For multilingual articles, this will be the title of the default language's content.
Example: "Default language title"
The description of the article. For multilingual articles, this will be the description of the default language's content.
Example: "Default language description"
The body of the article in HTML. For multilingual articles, this will be the body of the default language's content.
Example: "Default language body in html"
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
Example: "5017691"
Whether the article is published or is a draft. For multilingual articles, this will be the state of the default language's content.
Default "draft"
Enum"published""draft"
Example: "published"
The time when the article was created. For multilingual articles, this will be the timestamp of creation of the default language's content in seconds.
Example: 1672928359
The time when the article was last updated. For multilingual articles, this will be the timestamp of last update of the default language's content in seconds.
Example: 1672928610
The URL of the article. For multilingual articles, this will be the URL of the default language's content.
Example: "http://intercom.test/help/en/articles/3-default-language"
The id of the article's parent collection or section. An article without this field stands alone.
Example: "125685"
The ids of the article's parent collections or sections. An article without this field stands alone.
Example: [18,19]
The type of parent, which can either be a collection or section.
Example: "collection"
The default locale of the help center. This field is only returned for multilingual help centers.
Example: "en"
Response
application/json
{ "id": "45", "type": "article", "workspace_id": "this_is_an_id74_that_should_be_at_least_4", "parent_id": 148, "parent_type": "collection", "parent_ids": [], "statistics": { "type": "article_statistics", "views": 0, "conversations": 0, "reactions": 0, "happy_reaction_percentage": 0, "neutral_reaction_percentage": 0, "sad_reaction_percentage": 0 }, "tags": { "type": "tag.list", "tags": [] }, "title": "This is the article title", "description": "", "body": "", "author_id": 991267502, "state": "published", "created_at": 1734537292, "updated_at": 1734537292, "url": "http://help-center.test/myapp-74/en/articles/45-this-is-the-article-title" }
Bodyapplication/json
The title of the article.For multilingual articles, this will be the title of the default language's content.
Example: "Thanks for everything"
The description of the article. For multilingual articles, this will be the description of the default language's content.
Example: "Description of the Article"
The content of the article. For multilingual articles, this will be the body of the default language's content.
Example: "<p>This is the body in html</p>"
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
Example: 1295
Whether the article will be published or will be a draft. Defaults to draft. For multilingual articles, this will be the state of the default language's content.
Enum"published""draft"
Example: "draft"
The id of the article's parent collection or section. An article without this field stands alone.
Example: "18"
The type of parent, which can either be a collection or section.
Example: "collection"
- The production API server
https://api.intercom.io/articles/{id}
- The european API server
https://api.eu.intercom.io/articles/{id}
- The australian API server
https://api.au.intercom.io/articles/{id}
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X PUT \
https://api.intercom.io/articles/123 \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: Unstable' \
-d '{
"title": "Christmas is here!",
"body": "<p>New gifts in store for the jolly season</p>"
}'successful
The title of the article. For multilingual articles, this will be the title of the default language's content.
Example: "Default language title"
The description of the article. For multilingual articles, this will be the description of the default language's content.
Example: "Default language description"
The body of the article in HTML. For multilingual articles, this will be the body of the default language's content.
Example: "Default language body in html"
The id of the author of the article. For multilingual articles, this will be the id of the author of the default language's content. Must be a teammate on the help center's workspace.
Example: "5017691"
Whether the article is published or is a draft. For multilingual articles, this will be the state of the default language's content.
Default "draft"
Enum"published""draft"
Example: "published"
The time when the article was created. For multilingual articles, this will be the timestamp of creation of the default language's content in seconds.
Example: 1672928359
The time when the article was last updated. For multilingual articles, this will be the timestamp of last update of the default language's content in seconds.
Example: 1672928610
The URL of the article. For multilingual articles, this will be the URL of the default language's content.
Example: "http://intercom.test/help/en/articles/3-default-language"
The id of the article's parent collection or section. An article without this field stands alone.
Example: "125685"
The ids of the article's parent collections or sections. An article without this field stands alone.
Example: [18,19]
The type of parent, which can either be a collection or section.
Example: "collection"
The default locale of the help center. This field is only returned for multilingual help centers.
Example: "en"
Response
application/json
{ "id": "48", "type": "article", "workspace_id": "this_is_an_id80_that_should_be_at_least_4", "parent_id": 151, "parent_type": "collection", "parent_ids": [], "statistics": { "type": "article_statistics", "views": 0, "conversations": 0, "reactions": 0, "happy_reaction_percentage": 0, "neutral_reaction_percentage": 0, "sad_reaction_percentage": 0 }, "tags": { "type": "tag.list", "tags": [] }, "title": "Christmas is here!", "description": "", "body": "<p class=\"no-margin\">New gifts in store for the jolly season</p>", "author_id": 991267508, "state": "published", "created_at": 1734537297, "updated_at": 1734537298, "url": "http://help-center.test/myapp-80/en/articles/48-christmas-is-here" }
- The production API server
https://api.intercom.io/articles/{id}
- The european API server
https://api.eu.intercom.io/articles/{id}
- The australian API server
https://api.au.intercom.io/articles/{id}
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X DELETE \
https://api.intercom.io/articles/123 \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'Response
application/json
{ "id": "51", "object": "article", "deleted": true }
- The production API server
https://api.intercom.io/articles/search
- The european API server
https://api.eu.intercom.io/articles/search
- The australian API server
https://api.au.intercom.io/articles/search
- curl
- Node.js
- Ruby
- PHP
- Python
- Java
- Go
- C#
- R
curl -i -X GET \
'https://api.intercom.io/articles/search?phrase=Getting+started&state=published&help_center_id=123&highlight=true' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: Unstable'Search successful
Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.
Response
application/json
{ "type": "list", "total_count": 1, "data": { "articles": [ … ], "highlights": [] }, "pages": { "type": "pages", "page": 1, "total_pages": 1, "per_page": 10 } }
Custom Channel Events
With the "Custom Channel" integration, you can bring Fin and Intercom capabilities to your own platform via API, enabling powerful custom integrations.
Intercom treats your integration like any other Intercom channel, allowing your application and Intercom to exchange events seamlessly. This makes it possible, for example, for your users to interact with Fin directly within your own application’s UI.
Note: "Fin over API" is currently under managed availability. Please reach out to your accounts team to discuss access and tailored, hands-on support.
Operations
Custom Object Instances
Everything about your Custom Object instances.
Permission Requirements
From now on, to access this endpoint, you need additional permissions. Please head over to the Developer Hub app package authentication settings to configure the required permissions.
Operations