Intercom API (unofficial showcase)
POST/companies/search

Search companies

Searches companies by attribute filters in a request body. Use query to specify filters and optionally provide pagination and sort; companies without associated users are excluded from the results.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
Intercom-Versionstringoptional
API version to use for the request. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Company search criteria, with optional pagination and sorting.

queryobjectrequired
A single filter or a group of filters used to select companies. You can nest filters up to two levels, with at most 15 filters in each AND or OR group; filter fields and values must use supported types and operators.
paginationobjectoptional
Optional pagination settings, including `per_page` to set the number of results and `starting_after` to continue from a cursor.
sortobjectoptional
An optional object to sort the results by.

3 status codes
200Returns a list of matching company objects, total result count, and cursor-based pagination metadata.
typestringoptional
The type of object - `list`.
Allowed:list
pagesobjectoptional
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_countintegeroptional
The total number of companies.
dataarray<Company>optional
An array containing Company Objects.
400Returned when the search query contains an invalid field or value, uses an incompatible operator, exceeds filter nesting or group limits, or specifies an invalid sort order.

One documented failure

  • invalid_field

    segment_id is not a valid search field

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
401Returned when the request is unauthorized.

One documented failure

  • unauthorized

    Access Token Invalid

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

The query field is required. A 400 is returned for invalid fields or incompatible filter values, more than two levels of nested filters, more than 15 filters in an AND or OR group, or an invalid sort order; plan.id and plan.name are not searchable. A 401 is returned when the request is unauthorized.