Home
/
REST API Reference
/
Companies
/
Scroll over all companies

Intercom API (2.13)

The Intercom API reference.

Download OpenAPI description
api.intercom.io.json
api.intercom.io.yaml
Overview
URL

https://developers.intercom.com

License

MIT

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/

Admins

Everything about your Admins

Operations

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

Articles

Everything about your Articles

Operations

Companies

Everything about your Companies

Operations

Company

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.

typestring

Value is company

Value"company"
Example: "company"
idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
namestring

The name of the company.

Example: "Blue Sun"
app_idstring

The Intercom defined code of the workspace the company is associated to.

Example: "ecahpwf5"
planobject
company_idstring

The company id you have defined for the company.

Example: "6"
remote_created_atinteger

The time the company was created by you.

Example: 1663597223
created_atinteger

The time the company was added in Intercom.

Example: 1663597223
updated_atinteger

The last time the company was updated.

Example: 1663597223
last_request_atinteger

The time the company last recorded making a request.

Example: 1663597223
sizeinteger

The number of employees in the company.

Example: 100
websitestring

The URL for the company website.

Example: "https://www.intercom.com"
industrystring

The industry that the company operates in.

Example: "Software"
monthly_spendinteger

How much revenue the company generates for your business.

Example: 100
session_countinteger

How many sessions the company has recorded.

Example: 100
user_countinteger

The number of users in the company.

Example: 100
custom_attributesobject

The custom attributes you have set on the company.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
tagsobject

The list of tags associated with the company

segmentsobject

The list of segments associated with 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": [ … ]
  }
}

Create or Update a company

Request

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.

Using `company_id`

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.

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
Bodyapplication/json
namestring

The name of the Company

Example: "Intercom"
company_idstring

The company id you have defined for the company. Can't be updated

Example: "625e90fc55ab113b6d92175f"
planstring

The name of the plan you have associated with the company.

Example: "Enterprise"
sizeinteger

The number of employees in this company.

Example: "100"
websitestring

The URL for this company's website. Please note that the value specified here is not validated. Accepts any string.

Example: "https://www.example.com"
industrystring

The industry that this company operates in.

Example: "Manufacturing"
custom_attributesobject

A hash of key/value pairs containing any other data about the company you want Intercom to store.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
remote_created_atinteger

The time the company was created by you.

Example: 1394531169
monthly_spendinteger

How much revenue the company generates for your business. Note that this will truncate floats. i.e. it only allow for whole integers, 155.98 will be truncated to 155. Note that this has an upper limit of 2**31-1 or 2147483647..

Example: 1000
curl -i -X POST \
  https://api.intercom.io/companies \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.13' \
  -d '{
    "company_id": "company_remote_id",
    "name": "my company",
    "remote_created_at": 1374138000
  }'

Responses

Successful

Bodyapplication/json
typestring

Value is company

Value"company"
Example: "company"
idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
namestring

The name of the company.

Example: "Blue Sun"
app_idstring

The Intercom defined code of the workspace the company is associated to.

Example: "ecahpwf5"
planobject
company_idstring

The company id you have defined for the company.

Example: "6"
remote_created_atinteger

The time the company was created by you.

Example: 1663597223
created_atinteger

The time the company was added in Intercom.

Example: 1663597223
updated_atinteger

The last time the company was updated.

Example: 1663597223
last_request_atinteger

The time the company last recorded making a request.

Example: 1663597223
sizeinteger

The number of employees in the company.

Example: 100
websitestring

The URL for the company website.

Example: "https://www.intercom.com"
industrystring

The industry that the company operates in.

Example: "Software"
monthly_spendinteger

How much revenue the company generates for your business.

Example: 100
session_countinteger

How many sessions the company has recorded.

Example: 100
user_countinteger

The number of users in the company.

Example: 100
custom_attributesobject

The custom attributes you have set on the company.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
tagsobject

The list of tags associated with the company

segmentsobject

The list of segments associated with the company

Response
application/json
{
  "type": "company",
  "company_id": "company_remote_id",
  "id": "677c54f86abd011ad17ff451",
  "app_id": "this_is_an_id147_that_should_be_at_least_",
  "name": "my company",
  "remote_created_at": 1374138000,
  "created_at": 1736201464,
  "updated_at": 1736201464,
  "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"
  }
}

Retrieve companies

Request

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}

Query
namestring

The name of the company to filter by.

Example: name=my company
company_idstring

The company_id of the company to filter by.

Example: company_id=12345
tag_idstring

The tag_id of the company to filter by.

Example: tag_id=678910
segment_idstring

The segment_id of the company to filter by.

Example: segment_id=98765
pageinteger

The page of results to fetch. Defaults to first page

Example: page=1
per_pageinteger

How many results to display per page. Defaults to 15

Example: per_page=15
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X GET \
  'https://api.intercom.io/companies?company_id=12345&name=my%20company&page=1&per_page=15&segment_id=98765&tag_id=678910' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

The type of object - list.

Value"list"
Example: "list"
pagesobject or null(Cursor based pages)

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.

total_countinteger

The total number of companies.

Example: 100
dataArray of objects(Company)

An array containing Company Objects.

Response
application/json
{
  "type": "list",
  "data": [
    { … }
  ],
  "pages": {
    "type": "pages",
    "next": null,
    "page": 1,
    "per_page": 15,
    "total_pages": 1
  },
  "total_count": 1
}

Retrieve a company by ID

Request

You can fetch a single company.

Path
idstringrequired

The unique identifier for the company which is given by Intercom

Example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X GET \
  https://api.intercom.io/companies/5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

Value is company

Value"company"
Example: "company"
idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
namestring

The name of the company.

Example: "Blue Sun"
app_idstring

The Intercom defined code of the workspace the company is associated to.

Example: "ecahpwf5"
planobject
company_idstring

The company id you have defined for the company.

Example: "6"
remote_created_atinteger

The time the company was created by you.

Example: 1663597223
created_atinteger

The time the company was added in Intercom.

Example: 1663597223
updated_atinteger

The last time the company was updated.

Example: 1663597223
last_request_atinteger

The time the company last recorded making a request.

Example: 1663597223
sizeinteger

The number of employees in the company.

Example: 100
websitestring

The URL for the company website.

Example: "https://www.intercom.com"
industrystring

The industry that the company operates in.

Example: "Software"
monthly_spendinteger

How much revenue the company generates for your business.

Example: 100
session_countinteger

How many sessions the company has recorded.

Example: 100
user_countinteger

The number of users in the company.

Example: 100
custom_attributesobject

The custom attributes you have set on the company.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
tagsobject

The list of tags associated with the company

segmentsobject

The list of segments associated with the company

Response
application/json
{
  "type": "company",
  "company_id": "1",
  "id": "677c54ff6abd011ad17ff464",
  "app_id": "this_is_an_id159_that_should_be_at_least_",
  "name": "company1",
  "remote_created_at": 1736201471,
  "created_at": 1736201471,
  "updated_at": 1736201471,
  "monthly_spend": 0,
  "session_count": 0,
  "user_count": 1,
  "tags": {
    "type": "tag.list",
    "tags": []
  },
  "segments": {
    "type": "segment.list",
    "segments": []
  },
  "plan": {},
  "custom_attributes": {}
}

Update a company

Request

You can update a single company using the Intercom provisioned id.

Using `company_id`

When updating a company it is not possible to update company_id. This can only be set once upon creation of the company.

Path
idstringrequired

The unique identifier for the company which is given by Intercom

Example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X PUT \
  https://api.intercom.io/companies/5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

Value is company

Value"company"
Example: "company"
idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
namestring

The name of the company.

Example: "Blue Sun"
app_idstring

The Intercom defined code of the workspace the company is associated to.

Example: "ecahpwf5"
planobject
company_idstring

The company id you have defined for the company.

Example: "6"
remote_created_atinteger

The time the company was created by you.

Example: 1663597223
created_atinteger

The time the company was added in Intercom.

Example: 1663597223
updated_atinteger

The last time the company was updated.

Example: 1663597223
last_request_atinteger

The time the company last recorded making a request.

Example: 1663597223
sizeinteger

The number of employees in the company.

Example: 100
websitestring

The URL for the company website.

Example: "https://www.intercom.com"
industrystring

The industry that the company operates in.

Example: "Software"
monthly_spendinteger

How much revenue the company generates for your business.

Example: 100
session_countinteger

How many sessions the company has recorded.

Example: 100
user_countinteger

The number of users in the company.

Example: 100
custom_attributesobject

The custom attributes you have set on the company.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
tagsobject

The list of tags associated with the company

segmentsobject

The list of segments associated with the company

Response
application/json
{
  "type": "company",
  "company_id": "1",
  "id": "677c55036abd011ad17ff46e",
  "app_id": "this_is_an_id165_that_should_be_at_least_",
  "name": "company2",
  "remote_created_at": 1736201475,
  "created_at": 1736201475,
  "updated_at": 1736201475,
  "monthly_spend": 0,
  "session_count": 0,
  "user_count": 1,
  "tags": {
    "type": "tag.list",
    "tags": []
  },
  "segments": {
    "type": "segment.list",
    "segments": []
  },
  "plan": {},
  "custom_attributes": {}
}

Delete a company

Request

You can delete a single company.

Path
idstringrequired

The unique identifier for the company which is given by Intercom

Example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X DELETE \
  https://api.intercom.io/companies/5f4d3c1c-7b1b-4d7d-a97e-6095715c6632 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
idstring

The unique identifier for the company which is given by Intercom.

Example: "5b7e8b2f-7a1a-4e6c-8e1b-4f9d4f4c4d4f"
objectstring

The type of object which was deleted. - company

Value"company"
Example: "company"
deletedboolean

Whether the company was deleted successfully or not.

Example: true
Response
application/json
{
  "id": "677c55076abd011ad17ff478",
  "object": "company",
  "deleted": true
}

List attached contacts

Request

You can fetch a list of all contacts that belong to a company.

Path
idstringrequired

The unique identifier for the company which is given by Intercom

Example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X GET \
  https://api.intercom.io/companies/5f4d3c1c-7b1b-4d7d-a97e-6095715c6632/contacts \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

The type of object - list

Value"list"
Example: "list"
dataArray of objects(Contact)

An array containing Contact Objects

total_countinteger

The total number of contacts

Example: 100
pagesobject or null(Cursor based pages)

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",
  "data": [],
  "total_count": 0,
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 50,
    "total_pages": 0
  }
}

List attached segments for companies

Request

You can fetch a list of all segments that belong to a company.

Path
idstringrequired

The unique identifier for the company which is given by Intercom

Example: 5f4d3c1c-7b1b-4d7d-a97e-6095715c6632
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X GET \
  https://api.intercom.io/companies/5f4d3c1c-7b1b-4d7d-a97e-6095715c6632/segments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

The type of object - list

Value"list"
Example: "list"
dataArray of objects(Segment)

An array containing Segment Objects

Response
application/json
{
  "type": "list",
  "data": []
}

List all companies

Request

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.

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 starting_after param.

Query
pageinteger

The page of results to fetch. Defaults to first page

Example: page=1
per_pageinteger

How many results to return per page. Defaults to 15

Example: per_page=15
orderstring

asc or desc. Return the companies in ascending or descending order. Defaults to desc

Example: order=desc
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X POST \
  'https://api.intercom.io/companies/list?order=desc&page=1&per_page=15' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

The type of object - list.

Value"list"
Example: "list"
pagesobject or null(Cursor based pages)

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.

total_countinteger

The total number of companies.

Example: 100
dataArray of objects(Company)

An array containing Company Objects.

Response
application/json
{
  "type": "list",
  "data": [
    { … }
  ],
  "pages": {
    "type": "pages",
    "next": null,
    "page": 1,
    "per_page": 15,
    "total_pages": 1
  },
  "total_count": 1
}

Scroll over all companies

Request

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. You'll get an error message if you try to have more than one open per app.
  • If the scroll isn't used for 1 minute, it expires and calls with that scroll param will fail
  • If the end of the scroll is reached, "companies" will be empty and the scroll parameter will expire
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.

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.

Query
scroll_paramstring
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X GET \
  'https://api.intercom.io/companies/scroll?scroll_param=string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

The type of object - list

Value"list"
Example: "list"
dataArray of objects(Company)
pagesobject or null(Cursor based pages)

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.

total_countinteger or null

The total number of companies

Example: 100
scroll_paramstring

The scroll parameter to use in the next request to fetch the next page of results.

Example: "25b649f7-4d33-4ef6-88f5-60e5b8244309"
Response
application/json
{
  "type": "list",
  "data": [
    { … }
  ],
  "pages": null,
  "total_count": null,
  "scroll_param": "40309d82-25c6-4ea6-aba2-5a3b2b1ce31c"
}

Attach a Contact to a Company

Request

You can attach a company to a single contact.

Path
idstringrequired

The unique identifier for the contact which is given by Intercom

Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
Bodyapplication/json
idstringrequired

The unique identifier for the company which is given by Intercom

Example: "58a430d35458202d41b1e65b"
curl -i -X POST \
  'https://api.intercom.io/contacts/{id}/companies' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: 2.13' \
  -d '{
    "id": "677c55186abd011ad17ff4a3"
  }'

Responses

Successful

Bodyapplication/json
typestring

Value is company

Value"company"
Example: "company"
idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
namestring

The name of the company.

Example: "Blue Sun"
app_idstring

The Intercom defined code of the workspace the company is associated to.

Example: "ecahpwf5"
planobject
company_idstring

The company id you have defined for the company.

Example: "6"
remote_created_atinteger

The time the company was created by you.

Example: 1663597223
created_atinteger

The time the company was added in Intercom.

Example: 1663597223
updated_atinteger

The last time the company was updated.

Example: 1663597223
last_request_atinteger

The time the company last recorded making a request.

Example: 1663597223
sizeinteger

The number of employees in the company.

Example: 100
websitestring

The URL for the company website.

Example: "https://www.intercom.com"
industrystring

The industry that the company operates in.

Example: "Software"
monthly_spendinteger

How much revenue the company generates for your business.

Example: 100
session_countinteger

How many sessions the company has recorded.

Example: 100
user_countinteger

The number of users in the company.

Example: 100
custom_attributesobject

The custom attributes you have set on the company.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
tagsobject

The list of tags associated with the company

segmentsobject

The list of segments associated with the company

Response
application/json
{
  "type": "company",
  "company_id": "1",
  "id": "677c55186abd011ad17ff4a3",
  "app_id": "this_is_an_id197_that_should_be_at_least_",
  "name": "company6",
  "remote_created_at": 1736201496,
  "created_at": 1736201496,
  "updated_at": 1736201496,
  "monthly_spend": 0,
  "session_count": 0,
  "user_count": 1,
  "tags": {
    "type": "tag.list",
    "tags": []
  },
  "segments": {
    "type": "segment.list",
    "segments": []
  },
  "plan": {},
  "custom_attributes": {}
}

List attached companies for contact

Request

You can fetch a list of companies that are associated to a contact.

Path
idstringrequired

The unique identifier for the contact which is given by Intercom

Example: 63a07ddf05a32042dffac965
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X GET \
  https://api.intercom.io/contacts/63a07ddf05a32042dffac965/companies \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

successful

Bodyapplication/json
typestring

The type of object

Value"list"
Example: "list"
companiesArray of objects(Company)

An array containing Company Objects

total_countinteger

The total number of companies associated to this contact

Example: 100
pagesobject(Pagination Object)

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.

Response
application/json
{
  "type": "list",
  "data": [
    { … }
  ],
  "pages": {
    "type": "pages",
    "next": null,
    "page": 1,
    "per_page": 50,
    "total_pages": 1
  },
  "total_count": 1
}

Detach a contact from a company

Request

You can detach a company from a single contact.

Path
contact_idstringrequired

The unique identifier for the contact which is given by Intercom

Example: 58a430d35458202d41b1e65b
idstringrequired

The unique identifier for the company which is given by Intercom

Example: 58a430d35458202d41b1e65b
Headers
Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default 2.13
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example: 2.13
curl -i -X DELETE \
  https://api.intercom.io/contacts/58a430d35458202d41b1e65b/companies/58a430d35458202d41b1e65b \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.13'

Responses

Successful

Bodyapplication/json
typestring

Value is company

Value"company"
Example: "company"
idstring

The Intercom defined id representing the company.

Example: "531ee472cce572a6ec000006"
namestring

The name of the company.

Example: "Blue Sun"
app_idstring

The Intercom defined code of the workspace the company is associated to.

Example: "ecahpwf5"
planobject
company_idstring

The company id you have defined for the company.

Example: "6"
remote_created_atinteger

The time the company was created by you.

Example: 1663597223
created_atinteger

The time the company was added in Intercom.

Example: 1663597223
updated_atinteger

The last time the company was updated.

Example: 1663597223
last_request_atinteger

The time the company last recorded making a request.

Example: 1663597223
sizeinteger

The number of employees in the company.

Example: 100
websitestring

The URL for the company website.

Example: "https://www.intercom.com"
industrystring

The industry that the company operates in.

Example: "Software"
monthly_spendinteger

How much revenue the company generates for your business.

Example: 100
session_countinteger

How many sessions the company has recorded.

Example: 100
user_countinteger

The number of users in the company.

Example: 100
custom_attributesobject

The custom attributes you have set on the company.

Example: {"paid_subscriber":true,"monthly_spend":155.5,"team_mates":9}
tagsobject

The list of tags associated with the company

segmentsobject

The list of segments associated with the company

Response
application/json
{
  "type": "company",
  "company_id": "1",
  "id": "677c551e6abd011ad17ff4b3",
  "app_id": "this_is_an_id205_that_should_be_at_least_",
  "name": "company8",
  "remote_created_at": 1736201502,
  "created_at": 1736201502,
  "updated_at": 1736201502,
  "monthly_spend": 0,
  "session_count": 0,
  "user_count": 0,
  "tags": {
    "type": "tag.list",
    "tags": []
  },
  "segments": {
    "type": "segment.list",
    "segments": []
  },
  "plan": {},
  "custom_attributes": {}
}

Contacts

Everything about your contacts

Operations

Conversations

Everything about your Conversations

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

Data Attributes

Everything about your Data Attributes

Operations

Data Events

Everything about your Data Events

Operations

Data Export

Everything about your Data Exports

Operations

Help Center

Everything about your Help Center

Operations

Messages

Everything about your messages

Operations

News

Everything about your News

Operations

Notes

Everything about your Notes

Operations

Segments

Everything about your Segments

Operations

Subscription Types

Everything about subscription types

Operations

Switch

Everything about Switch

Operations

Tags

Everything about tags

Operations

Teams

Everything about your Teams

Operations

Ticket States

Everything about your ticket states

Operations

Ticket Type Attributes

Everything about your ticket type attributes

Operations

Ticket Types

Everything about your ticket types

Operations

Tickets

Everything about your tickets

Operations

Visitors

Everything about your Visitors

Operations

Models