The intercom API reference.
URL https://developers.intercom.com
License MIT
The intercom API reference.
Companies allow you to represent organizations using your product. Each company will have its own description and be associated with contacts. You can fetch, create, update and list companies.
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company last recorded making a request.
The custom attributes you have set on the company.
{ "type": "company", "id": "531ee472cce572a6ec000006", "name": "Blue Sun", "app_id": "ecahpwf5", "plan": { "type": "plan", "id": "269315", "name": "Pro" }, "company_id": "6", "remote_created_at": 1663597223, "created_at": 1663597223, "updated_at": 1663597223, "last_request_at": 1663597223, "size": 100, "website": "https://www.intercom.com", "industry": "Software", "monthly_spend": 100, "session_count": 100, "user_count": 100, "custom_attributes": { "paid_subscriber": true, "monthly_spend": 155.5, "team_mates": 9 }, "tags": { "type": "tag.list", "tags": [ … ] }, "segments": { "type": "segment.list", "segments": [ … ] } }
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 company_id in a POST request, if not found via company_id, the new company will be created, if found, that company will be updated.
You can set a unique company_id value when creating a company. However, it is not possible to update company_id. Be sure to set a unique value once upon creation of the company.
The company id you have defined for the company. Can't be updated
The URL for this company's website. Please note that the value specified here is not validated. Accepts any string.
A hash of key/value pairs containing any other data about the company you want Intercom to store.
curl -i -X POST \
https://api.intercom.io/companies \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.11' \
-d '{
"company_id": "company_remote_id",
"name": "my company",
"remote_created_at": 1374138000
}'Successful
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company last recorded making a request.
The custom attributes you have set on the company.
{ "type": "company", "company_id": "company_remote_id", "id": "667d607c8a68186f43bafd1e", "app_id": "this_is_an_id116_that_should_be_at_least_", "name": "my company", "remote_created_at": 1374138000, "created_at": 1719492732, "updated_at": 1719492732, "monthly_spend": 0, "session_count": 0, "user_count": 0, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "plan": {}, "custom_attributes": { "creation_source": "api" } }
You can fetch a single company by passing in company_id or name.
https://api.intercom.io/companies?name={name}
https://api.intercom.io/companies?company_id={company_id}
You can fetch all companies and filter by segment_id or tag_id as a query parameter.
https://api.intercom.io/companies?tag_id={tag_id}
https://api.intercom.io/companies?segment_id={segment_id}
curl -i -X GET \
'https://api.intercom.io/companies?company_id=string&name=string&page=0&per_page=0&segment_id=string&tag_id=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'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.
An array containing Company Objects.
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company was created by you.
The time the company last recorded making a request.
How much revenue the company generates for your business.
The custom attributes you have set on the company.
{ "type": "list", "data": [ { … } ], "pages": { "type": "pages", "next": null, "page": 1, "per_page": 15, "total_pages": 1 }, "total_count": 1 }
curl -i -X GET \
'https://api.intercom.io/companies/{company_id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'Successful
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company last recorded making a request.
The custom attributes you have set on the company.
{ "type": "company", "company_id": "1", "id": "667d60808a68186f43bafd31", "app_id": "this_is_an_id128_that_should_be_at_least_", "name": "company1", "remote_created_at": 1719492736, "created_at": 1719492736, "updated_at": 1719492736, "monthly_spend": 0, "session_count": 0, "user_count": 1, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "plan": {}, "custom_attributes": {} }
curl -i -X PUT \
'https://api.intercom.io/companies/{company_id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'Successful
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company last recorded making a request.
The custom attributes you have set on the company.
{ "type": "company", "company_id": "1", "id": "667d60828a68186f43bafd3b", "app_id": "this_is_an_id134_that_should_be_at_least_", "name": "company2", "remote_created_at": 1719492738, "created_at": 1719492738, "updated_at": 1719492738, "monthly_spend": 0, "session_count": 0, "user_count": 1, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "plan": {}, "custom_attributes": {} }
curl -i -X DELETE \
'https://api.intercom.io/companies/{company_id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'{ "id": "667d60848a68186f43bafd45", "object": "company", "deleted": true }
curl -i -X GET \
'https://api.intercom.io/companies/{company_id}/contacts?page=0&per_page=0' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'Successful
An array containing Contact Objects
The unique identifier for the contact which is given by Intercom.
The unique identifier for the contact which is provided by the Client.
The id of the workspace which the contact belongs to.
The contacts phone number normalized to the E164 format
The id of an admin that has been assigned account ownership of the contact.
Whether the contact has had an email sent to them hard bounce.
Whether the contact has marked an email sent to them as spam.
Whether the contact is unsubscribed from emails.
(UNIX timestamp) The time when the contact was created.
(UNIX timestamp) The time when the contact was last updated.
(UNIX timestamp) The time specified for when a contact signed up.
(UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
(UNIX timestamp) The time when the contact last messaged in.
(UNIX timestamp) The time when the contact was last messaged.
(UNIX timestamp) The time when the contact last opened an email.
(UNIX timestamp) The time when the contact last clicked a link in an email.
A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
The name of the browser which the contact is using.
The version of the browser which the contact is using.
The language set by the browser which the contact is using.
The operating system which the contact is using.
The name of the Android app which the contact is using.
The version of the Android app which the contact is using.
The Android device which the contact is using.
The version of the Android OS which the contact is using.
The version of the Android SDK which the contact is using.
(UNIX timestamp) The time when the contact was last seen on an Android device.
The name of the iOS app which the contact is using.
The version of the iOS app which the contact is using.
The version of iOS which the contact is using.
The version of the iOS SDK which the contact is using.
(UNIX timestamp) The last time the contact used the iOS app.
An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.
An object containing location metadata about a Intercom contact.
The country that the contact is located in
The overal region that the contact is located in
An object containing social profiles that a contact has.
A list of social profiles objects associated with the contact.
value is "social_profile"
The name of the Social media profile
{ "type": "list", "data": [], "total_count": 0, "pages": { "type": "pages", "page": 1, "per_page": 50, "total_pages": 0 } }
curl -i -X GET \
'https://api.intercom.io/companies/{company_id}/segments' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'{ "type": "list", "data": [] }
You 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 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.
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 starting_after param.
curl -i -X POST \
'https://api.intercom.io/companies/list?order=string&page=0&per_page=0' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'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.
An array containing Company Objects.
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company was created by you.
The time the company last recorded making a request.
How much revenue the company generates for your business.
The custom attributes you have set on the company.
{ "type": "list", "data": [ { … } ], "pages": { "type": "pages", "next": null, "page": 1, "per_page": 15, "total_pages": 1 }, "total_count": 1 }
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.
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.
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.
curl -i -X GET \
'https://api.intercom.io/companies/scroll?scroll_param=string' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'Successful
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company was created by you.
The time the company last recorded making a request.
How much revenue the company generates for your business.
The custom attributes you have set on the company.
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", "data": [ { … } ], "pages": null, "total_count": null, "scroll_param": "12d403b5-dc79-47b5-8ea1-01a5ac8cb6cc" }
curl -i -X POST \
'https://api.intercom.io/contacts/{contact_id}/companies' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Content-Type: application/json' \
-H 'Intercom-Version: 2.11' \
-d '{
"id": "667d608d8a68186f43bafd70"
}'Successful
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company last recorded making a request.
The custom attributes you have set on the company.
{ "type": "company", "company_id": "1", "id": "667d608d8a68186f43bafd70", "app_id": "this_is_an_id166_that_should_be_at_least_", "name": "company6", "remote_created_at": 1719492749, "created_at": 1719492749, "updated_at": 1719492749, "monthly_spend": 0, "session_count": 0, "user_count": 1, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "plan": {}, "custom_attributes": {} }
curl -i -X GET \
'https://api.intercom.io/contacts/{contact_id}/companies?page=0&per_page=0' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'successful
An array containing Company Objects
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The company id you have defined for the company.
The time the company was created by you.
The time the company was added in Intercom.
The time the company last recorded making a request.
The URL for the company website.
How much revenue the company generates for your business.
The custom attributes you have set on the company.
The majority of list resources in the API are paginated to allow clients to traverse data over multiple requests.
Their responses are likely to contain a pages object that hosts pagination links which a client can use to paginate through the data without having to construct a query. The link relations for the pages field are as follows.
{ "type": "list", "data": [ { … } ], "pages": { "type": "pages", "next": null, "page": 1, "per_page": 50, "total_pages": 1 }, "total_count": 1 }
curl -i -X DELETE \
'https://api.intercom.io/contacts/{contact_id}/companies/{company_id}' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
-H 'Intercom-Version: 2.11'Successful
The Intercom defined id representing the company.
The Intercom defined code of the workspace the company is associated to.
The time the company last recorded making a request.
The custom attributes you have set on the company.
{ "type": "company", "company_id": "1", "id": "667d60918a68186f43bafd80", "app_id": "this_is_an_id174_that_should_be_at_least_", "name": "company8", "remote_created_at": 1719492753, "created_at": 1719492753, "updated_at": 1719492753, "monthly_spend": 0, "session_count": 0, "user_count": 0, "tags": { "type": "tag.list", "tags": [] }, "segments": { "type": "segment.list", "segments": [] }, "plan": {}, "custom_attributes": {} }