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}

The list is paged by page number. There is a limit of 10,000 companies; beyond that the request returns a 400 error and you should use the scroll endpoint instead.

Security

bearerAuth

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

typestring

Set to user or users, together with company_id or name, to return that company's users instead of the company. The response is then a user.list object with a users array in the legacy user format, paged with page and per_page (default 50).

Enum:"user""users"

Example:type=users

pageinteger

The page of results to fetch. Defaults to first page

Example:page=1

per_pageinteger, <= 60

How many results to display per page. Defaults to 15. A value above 60 returns a 400 error with code parameter_invalid.

Example:per_page=15

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:2.17

curl -i -X GET \
  'https://api.intercom.io/companies?name=my%20company&company_id=12345&tag_id=678910&segment_id=98765&type=users&page=1&per_page=15' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

Responses

Successful

Bodyapplication/json

One of:

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. Returned HTML-escaped, for example & as &.

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. Returned HTML-escaped, for example & as &.

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

Always returned empty. Fetch a company's segments with the list attached segments endpoint.

notesobject

The list of notes associated with the company

Response

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