Home
/
REST API Reference
/
Companies
/
List all companies

Intercom API (2.11)

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

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: "Example Company Inc."
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": "Example Company Inc.",
  "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: "Technology"
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
  }'

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: "Example Company Inc."
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'

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