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.

{% admonition type="warning" name="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. {% /admonition %}

Merged Contacts

Contacts that have been merged (via POST /contacts/merge) are excluded from search results. If a contact was recently merged into another, it will no longer appear in queries filtered by updated_at or any other field. Only the target contact from the merge remains searchable.

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

Timestamp fields (created_at, updated_at etc.) and Date custom attributes are matched by calendar day. Sub-day precision (hour, minute, second) is not supported.

The day boundary uses your workspace's timezone, so the same query can return different results on two workspaces in different timezones.

Because the value is truncated to a day:

• = matches the whole day.
• > matches from the start of the next day, not from the instant you passed.
• < matches everything before the start of that day.

The !=, >=, <=, IN and NIN operators are not supported on Date fields and return an error.

Example, on a workspace set to UTC. Searching for created_at greater than 1577869200 (January 1st, 2020 9:00 AM UTC) truncates that value to 1577836800 (January 1st, 2020 12:00 AM UTC). Because > starts at the next day, the results begin from January 2nd, 2020 12:00 AM UTC - not from 9:00 AM on January 1st. On a workspace in another timezone, the boundaries fall on that timezone's midnight instead.

To get contacts created on January 1st, 2020, search for created_at equal to 1577836800.

Only search queries behave this way. Responses still carry the full UNIX timestamp, and sorting uses the full value.

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

Accepted Operators

{% admonition type="warning" name="Operators not supported on Date fields" %} Date fields (created_at, updated_at, and any Date custom attribute) do not support the !=, >=, or <= operators. Using them returns an error. {% /admonition %}

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 ("="). Which operators are valid depends on the field's type - see the "Valid Types" column below. Searching by tag_id supports only the = and != operators.

{
  "query": {
    "field": "created_at",
    "operator": ">"
  },
  "pagination": {
    "per_page": 2,
    "starting_after": "your-cursor-from-response"
  }
}

{
  "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": 123,
      "has_hard_bounced": true,
      "marked_email_as_spam": true,
      "unsubscribed_from_emails": true,
      "created_at": 1571672154,
      "updated_at": 1571672154,
      "signed_up_at": 1571672154,
      "last_seen_at": 1571672154,
      "last_replied_at": 1571672154,
      "last_contacted_at": 1571672154,
      "last_email_opened_at": 1571672154,
      "last_email_clicked_at": 1571672154,
      "language_override": "en",
      "browser": "Chrome",
      "browser_version": "80.0.3987.132",
      "browser_language": "en-US",
      "os": "Mac OS X",
      "android_app_name": "Intercom",
      "android_app_version": "5.0.0",
      "android_device": "Pixel 3",
      "android_os_version": "10",
      "android_sdk_version": "28",
      "android_last_seen_at": 1571672154,
      "ios_app_name": "Intercom",
      "ios_app_version": "5.0.0",
      "ios_device": "iPhone 11",
      "ios_os_version": "13.3.1",
      "ios_sdk_version": "13.3.1",
      "ios_last_seen_at": 1571672154,
      "avatar": {
        "type": "avatar",
        "image_url": "https://example.org/128Wash.jpg"
      },
      "tags": {
        "data": [
          {
            "type": "note",
            "id": "123",
            "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes"
          }
        ],
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/tags",
        "total_count": 100,
        "has_more": true
      },
      "notes": {
        "data": [
          {
            "type": "note",
            "id": "123",
            "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes"
          }
        ],
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/notes",
        "total_count": 100,
        "has_more": true
      },
      "companies": {
        "data": [
          {
            "id": "5ba682d23d7cf92bef87bfd4",
            "type": "company",
            "url": "/companies/5ba682d23d7cf92bef87bfd4"
          }
        ],
        "url": "/contacts/5ba682d23d7cf92bef87bfd4/companies",
        "total_count": 100,
        "has_more": true
      },
      "location": {
        "type": "location",
        "country": "Ireland",
        "region": "Dublin",
        "city": "Dublin"
      },
      "social_profiles": {
        "data": [
          {
            "type": "social_profile",
            "name": "Facebook",
            "url": "http://twitter.com/th1sland"
          }
        ]
      }
    }
  ],
  "total_count": 100,
  "pages": {
    "type": "pages",
    "page": 1,
    "next": {
      "per_page": 2,
      "starting_after": "your-cursor-from-response"
    },
    "per_page": 2,
    "total_pages": 13
  }
}