Search contacts

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

To search for contacts, you need to send a POST request to https://api.intercom.io/contacts/search.

This will accept a query object in the body which will define your filters in order to search for contacts.

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 50 results per page. See the pagination section for more details on how to use the starting_after param.

Contact Creation Delay

If a contact has recently been created, there is a possibility that it will not yet be available when searching. This means that it may not appear in the response. This delay can take a few minutes. If you need to be instantly notified it is recommended to use webhooks and iterate to see if they match your search filters.

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

Searching for Timestamp Fields

All timestamp fields (created_at, updated_at etc.) are indexed as Dates for Contact Search queries; Datetime queries are not currently supported. This means you can only query for timestamp fields by day - not hour, minute or second. For example, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM). The search results will then include Contacts created from January 2nd, 2020 12:00 AM onwards. If you'd like to get contacts created on January 1st, 2020 you should search with a created_at value equal (=) to 1577836800 (January 1st, 2020 12:00 AM). This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly.

Accepted Fields

Most key listed as part of the Contacts Model are searchable, whether writeable or not. 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 "foorbar").

FieldType
idString
roleString
Accepts user or lead
nameString
avatarString
owner_idInteger
emailString
email_domainString
phoneString
formatted_phoneString
external_idString
created_atDate (UNIX Timestamp)
signed_up_atDate (UNIX Timestamp)
updated_atDate (UNIX Timestamp)
last_seen_atDate (UNIX Timestamp)
last_contacted_atDate (UNIX Timestamp)
last_replied_atDate (UNIX Timestamp)
last_email_opened_atDate (UNIX Timestamp)
last_email_clicked_atDate (UNIX Timestamp)
language_overrideString
browserString
browser_languageString
osString
location.countryString
location.regionString
location.cityString
unsubscribed_from_emailsBoolean
marked_email_as_spamBoolean
has_hard_bouncedBoolean
ios_last_seen_atDate (UNIX Timestamp)
ios_app_versionString
ios_deviceString
ios_app_deviceString
ios_os_versionString
ios_app_nameString
ios_sdk_versionString
android_last_seen_atDate (UNIX Timestamp)
android_app_versionString
android_deviceString
android_app_nameString
andoid_sdk_versionString
segment_idString
tag_idString
custom_attributes.{attribute_name}String

Accepted Operators

Searching based on `created_at`

You cannot use the <= or >= operators to search by created_at.

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).

OperatorValid TypesDescription
=AllEquals
!=AllDoesn't Equal
INAllIn
Shortcut for OR queries
Values must be in Array
NINAllNot In
Shortcut for OR ! queries
Values must be in Array
>Integer
Date (UNIX Timestamp)
Greater than
<Integer
Date (UNIX Timestamp)
Lower than
~StringContains
!~StringDoesn't Contain
^StringStarts With
$StringEnds With
SecurityHTTP: bearerAuth
Request
header Parameters
Intercom-Version
string (intercom_version)
Default: 2.11

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

Enum: "1.0" "1.1" "1.2" "1.3" "1.4" "2.0" "2.1" "2.2" "2.3" "2.4" "2.5" "2.6" "2.7" "2.8" "2.9" "2.10" "2.11" "Unstable"
Example: 2.11
Request Body schema: application/json
required
Single Filter Search Request (object) or Multiple Filter Search Request (object)
object or null (Pagination: Starting After)
post
/contacts/search
Request samples
application/json
{ "query": { "operator": "AND", }, "pagination": { "per_page": 5 } }
Responses

200

successful

Response Schema: application/json
type
string

Always list

Value: "list"
Array of objects (Contact)

The list of contact objects

total_count
integer

A count of the total number of objects.

object 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.

401

Unauthorized

Response samples
application/json
{ "type": "list", "data": [ ], "total_count": 0, "pages": { "type": "pages", "page": 1, "per_page": 5, "total_pages": 0 } }