Search companies

Request

You can search for companies by the value of their attributes in order to fetch exactly the companies you want.

To search for companies, send a POST request to https://api.intercom.io/companies/search, with a query object in the body defining your filters.

Note that the API does not include companies who have no associated users in search results.

Optimizing search queries

Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 15 results per page. See the pagination section for more details on how to use the starting_after param.

Nesting & Limitations

You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). There are some limitations to the amount of multiple's there can be:

There's a limit of max 2 nested filters
There's a limit of max 15 filters for each AND or OR group

Accepted Fields

Most keys listed as part of the Companies Model are searchable. The value you search for has to match the accepted type, otherwise the query will fail (ie. as created_at accepts a date, the value cannot be a string such as "foobar").

Field	Type
company_id	String
name	String
created_at	Date (UNIX Timestamp)
updated_at	Date (UNIX Timestamp)
remote_created_at	Date (UNIX Timestamp)
last_request_at	Date (UNIX Timestamp)
monthly_spend	Integer
session_count	Integer
user_count	Integer
tag_id	String
custom_attributes.{attribute_name}	String

The plan.id and plan.name fields are not searchable and return a 400 error with code invalid_field.

Accepted Operators

The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string ("="). The operator has to be compatible with the field's type (eg. you cannot search with > for a given string value as it's only compatible for integer's and dates). Searching by tag_id supports only the = and != operators. The IN and NIN operators are not supported for Date fields.

Operator	Valid Types	Description
=	All	Equals
!=	All	Doesn't Equal
IN	All except Date and tag_id	In Shortcut for `OR` queries Values must be in Array
NIN	All except Date and tag_id	Not In Shortcut for `OR !` queries Values must be in Array
>	Integer Date (UNIX Timestamp)	Greater than
<	Integer Date (UNIX Timestamp)	Lower than
~	String	Contains
!~	String	Doesn't Contain
^	String	Starts With
$	String	Ends With

Sorting

Pass an optional sort object with a field and an order (ascending or descending; defaults to descending) to order the results. An invalid order returns a 400 error with code invalid_sort_order. tag_id can be used as a filter but not as a sort field.

Security

bearerAuth

Intercom-Versionstring(intercom_version)

Intercom API version.
By default, it's equal to the version set in the app package.

Default:"Preview"

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

Example:Preview

Bodyapplication/json

querySingle filter search request (object) or multiple filter search request (object)required

One of:

Search using Intercoms Search APIs with a single filter.

paginationobject or null(Pagination: Starting After)

sortobject

An optional object to sort the results by.

curl -i -X POST \
  https://api.intercom.io/companies/search \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "query": {
      "operator": "AND",
      "value": [
        {
          "field": "name",
          "operator": "=",
          "value": "my-company"
        }
      ]
    },
    "sort": {
      "field": "name",
      "order": "ascending"
    },
    "pagination": {
      "per_page": 5
    }
  }'

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

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