Skip to content
Home/
REST API Reference
/
/
Scroll over all companies

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. Starting a second one returns a 400 error with code scroll_exists.
  • If the scroll isn't used for 1 minute, it expires and calls with that scroll param return a 404 error with code not_found.
  • If the end of the scroll is reached, data will be empty and the scroll parameter will expire.

The response always has pages and total_count set to null. Use scroll_param to fetch the next page.

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.

Requires the read_users_companies OAuth scope.

Security
bearerAuth
Query
scroll_paramstring

The scroll_param from the previous response. Omit it to start a new scroll.

Example:scroll_param=69352cd2-ab5b-42ac-b004-a13d4e55e9b0
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 GET \
  'https://api.intercom.io/companies/scroll?scroll_param=69352cd2-ab5b-42ac-b004-a13d4e55e9b0' \
  -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"
dataArray of objects(Company)
pagesobject or null

Always null. Page through a scroll with scroll_param instead.

total_countinteger or null

Always null. The scroll endpoint does not count the companies it returns.

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
{
  "type": "list",
  "data": [
    { … }
  ],
  "pages": null,
  "total_count": null,
  "scroll_param": "69352cd2-ab5b-42ac-b004-a13d4e55e9b0"
}