Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

Intercom API (2.11)

The intercom API reference.

Download OpenAPI description
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

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.11
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:

2.11

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.11' \
  -d '{
    "company_id": "company_remote_id",
    "name": "my company",
    "remote_created_at": 1374138000
  }'
Experience it firsthand in the API Explorer!

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": "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" } }

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.11
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:

2.11

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'
Experience it firsthand in the API Explorer!

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.11
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:

2.11

curl -i -X GET \
  'https://api.intercom.io/companies/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.11'
Experience it firsthand in the API Explorer!

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": "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": {} }

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.11
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:

2.11

curl -i -X PUT \
  'https://api.intercom.io/companies/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.11'
Experience it firsthand in the API Explorer!

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": "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": {} }

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.11
Enum"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"
Example:

2.11

curl -i -X DELETE \
  'https://api.intercom.io/companies/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.11'
Experience it firsthand in the API Explorer!

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": "667d60848a68186f43bafd45", "object": "company", "deleted": true }