Skip to content
Home/
REST API Reference
/
/
List all companies

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. Going past that limit returns a 400 error with code bad_request.

Pagination

This endpoint pages by page number, not by cursor. Use the page and per_page query parameters, and the page, total_pages and next values in the pages object of the response. The default is 15 results per page. See the pagination section for more details.

Requires the write_users_companies OAuth scope. A token with only read scopes cannot call this endpoint.

Security
bearerAuth
Query
pageinteger

The page of results to fetch. Defaults to first page

Example:page=1
per_pageinteger, <= 60

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

Example:per_page=15
orderstring

asc or desc. Return the companies in ascending or descending order. Defaults to desc. Any other value returns a 400 error with code parameter_invalid.

Enum:"asc""desc"
Example:order=desc
Headers
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 POST \
  'https://api.intercom.io/companies/list?page=1&per_page=15&order=desc' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Intercom-Version: 2.17'

Responses

Successful

Bodyapplication/json
typestring

The type of object - list.

Value:"list"
Example:"list"
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.

total_countinteger

The total number of companies.

Example:100
dataArray of objects(Company)

An array containing Company Objects.

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