Search Contacts

Search contacts

POST/contacts/search

Use it in a workflow

Add a step and choose the Intercom connector.
Pick the Search Contacts action (under Contacts).
Fill in the fields below, then reference the result from later steps as {{searchContacts.response.data}}.

Request

Query parameters

include_merge_historyboolean

Pass `true` to include a `merge_history` array on each contact in the response. Only returned for contacts with a `user` role.

Default false

Headers

Intercom-Versionstring

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

One of1.01.11.21.31.42.02.12.22.32.42.52.62.72.82.92.102.112.122.132.142.152.16Default "2.16"

Request body

Enter the body as JSON in the step's Body field.

queryoneOfrequired

paginationobject

per_pageinteger

The number of results to fetch per page.

starting_afterstring

The cursor to use in the next request to get the next page of results.

sortobject

An optional object to sort the results by.

fieldstring

The field to sort the results on.

orderstring

The order to sort the results in. Defaults to `descending` when omitted. Values other than `ascending` or `descending` return a `400` error with code `invalid_sort_order`.

One ofascendingdescendingDefault "descending"

json

{
  "query": null,
  "pagination": {
    "per_page": 2,
    "starting_after": "your-cursor-from-response"
  },
  "sort": {
    "field": "created_at",
    "order": "descending"
  }
}

Response

Returns 200 with an object. Read it in later steps with {{searchContacts.response.data.<field>}}.

typestring

Always list

One oflist

dataarray<object>

The list of contact objects

typestring

The type of object.

idstring

The unique identifier for the contact which is given by Intercom.

external_idstring

The unique identifier for the contact which is provided by the Client.

workspace_idstring

The id of the workspace which the contact belongs to.

rolestring

The role of the contact.

emailstring

The contact's email.

email_domainstring

The contact's email domain.

phonestring

The contacts phone.

namestring

The contacts name.

owner_idstring

The id of an admin that has been assigned account ownership of the contact.

has_hard_bouncedboolean

Whether the contact has had an email sent to them hard bounce.

marked_email_as_spamboolean

Whether the contact has marked an email sent to them as spam.

unsubscribed_from_emailsboolean

Whether the contact is unsubscribed from emails.

created_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact was created.

updated_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact was last updated.

signed_up_atinteger (date-time)

(Unix timestamp in seconds) The time specified for when a contact signed up.

last_seen_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).

last_replied_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact last messaged in.

last_contacted_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact was last messaged.

last_email_opened_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact last opened an email.

last_email_clicked_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact last clicked a link in an email.

language_overridestring

A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.

browserstring

The name of the browser which the contact is using.

browser_versionstring

The version of the browser which the contact is using.

browser_languagestring

The language set by the browser which the contact is using.

osstring

The operating system which the contact is using.

android_app_namestring

The name of the Android app which the contact is using.

android_app_versionstring

The version of the Android app which the contact is using.

android_devicestring

The Android device which the contact is using.

android_os_versionstring

The version of the Android OS which the contact is using.

android_sdk_versionstring

The version of the Android SDK which the contact is using.

android_last_seen_atinteger (date-time)

(Unix timestamp in seconds) The time when the contact was last seen on an Android device.

ios_app_namestring

The name of the iOS app which the contact is using.

ios_app_versionstring

The version of the iOS app which the contact is using.

ios_devicestring

The iOS device which the contact is using.

ios_os_versionstring

The version of iOS which the contact is using.

ios_sdk_versionstring

The version of the iOS SDK which the contact is using.

ios_last_seen_atinteger (date-time)

(Unix timestamp in seconds) The last time the contact used the iOS app.

custom_attributesobject

The custom attributes which are set for the contact.

avatarobject2 fields

total_countinteger

A count of the total number of objects.

pagesobject

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.

typestring

the type of object `pages`.

One ofpages

pageinteger

The current page

nextobject2 fields

per_pageinteger

Number of results per page

total_pagesinteger

Total number of pages

json

{
  "type": "list",
  "data": [
    {
      "type": "contact",
      "id": "5ba682d23d7cf92bef87bfd4",
      "external_id": "f3b87a2e09d514c6c2e79b9a",
      "workspace_id": "ecahpwf5",
      "role": "user",
      "email": "joe@example.com",
      "email_domain": "example.com",
      "phone": "+1123456789",
      "name": "John Doe",
      "owner_id": "321",
      "has_hard_bounced": true,
      "marked_email_as_spam": true
    }
  ],
  "total_count": 100,
  "pages": {
    "type": "pages",
    "page": 1,
    "next": {
      "per_page": 2,
      "starting_after": "your-cursor-from-response"
    },
    "per_page": 2,
    "total_pages": 13
  }
}

Need more? See the Intercom guide for connection setup and behaviour shared by every action.

Was this page helpful?