Intercom API (unofficial showcase)
POST/contacts/search

Search contacts

Searches contacts by matching their attributes against filters in the request body. Use query to define a single filter or combine filters with AND and OR, and use pagination to retrieve results in pages. Timestamp and date filters are evaluated by calendar day in the workspace's timezone, and recently created contacts may take a few minutes to appear.

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

2 parameters · 3 body fields
include_merge_historybooleanoptional
Set to true to include a `merge_history` array for contacts with a user role. Defaults to false when omitted.
Default:false
Intercom-Versionstringoptional
The Intercom API version to use. Defaults to 2.17 when omitted.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Contact search criteria, pagination settings, and optional sort order. The query field is required.

queryobjectrequired
A filter or nested group of filters for selecting contacts. Use supported fields and operators, and provide values that match each field's type.
paginationobjectoptional
Cursor-based pagination settings for limiting results and continuing from a previous page.
sortobjectoptional
An optional object to sort the results by.

3 status codes
200Returns a contact list with matching contact objects, a total count, and cursor-based pagination details.
typestringoptional
Always list
Allowed:list
dataarray<Contact>optional
The list of contact objects
total_countintegeroptional
A count of the total number of objects.
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.
400Returned when `query` is missing or a filter, operator, value, pagination setting, or sort order is invalid.

One documented failure

  • invalid_sort_order

    Invalid sort order 'desc'. Must be one of: ascending, descending

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

A 400 is returned when query is missing or a filter, operator, value, or sort order is invalid; date fields do not support !=, >=, or <=, and filters allow at most two nesting levels and 15 filters per AND or OR group. A 401 is returned when the request is unauthorized. The query body field is required, and sort.order must be ascending or descending when supplied.