# 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  request to .

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  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  results per page.
  See the pagination section for more details on how to use the  param.
{% /admonition %}
### 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  accepts a date, the  cannot be a string such as ).

| Field                              | Type                           |
| ---------------------------------- | ------------------------------ |
| id                                 | String                         |
| role                               | StringAccepts user or lead |
| name                               | String                         |
| avatar                             | String                         |
| owner_id                           | Integer                        |
| email                              | String                         |
| email_domain                       | String                         |
| phone                              | String                         |
| external_id                        | String                         |
| created_at                         | Date (UNIX Timestamp)          |
| signed_up_at                       | Date (UNIX Timestamp)          |
| updated_at                         | Date (UNIX Timestamp)          |
| last_seen_at                       | Date (UNIX Timestamp)          |
| last_contacted_at                  | Date (UNIX Timestamp)          |
| last_replied_at                    | Date (UNIX Timestamp)          |
| last_email_opened_at               | Date (UNIX Timestamp)          |
| last_email_clicked_at              | Date (UNIX Timestamp)          |
| language_override                  | String                         |
| browser                            | String                         |
| browser_language                   | String                         |
| os                                 | String                         |
| location.country                   | String                         |
| location.region                    | String                         |
| location.city                      | String                         |
| unsubscribed_from_emails           | Boolean                        |
| marked_email_as_spam               | Boolean                        |
| has_hard_bounced                   | Boolean                        |
| ios_last_seen_at                   | Date (UNIX Timestamp)          |
| ios_app_version                    | String                         |
| ios_device                         | String                         |
| ios_app_device                     | String                         |
| ios_os_version                     | String                         |
| ios_app_name                       | String                         |
| ios_sdk_version                    | String                         |
| android_last_seen_at               | Date (UNIX Timestamp)          |
| android_app_version                | String                         |
| android_device                     | String                         |
| android_app_name                   | String                         |
| andoid_sdk_version                 | String                         |
| segment_id                         | String                         |
| tag_id                             | String                         |
| custom_attributes.{attribute_name} | String                         |

### Accepted Operators

{% admonition type="warning" name="Searching based on " %}
  You cannot use the  operators to search by .
{% /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 (). 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).

| Operator | Valid Types                      | Description                                                      |
| :------- | :------------------------------- | :--------------------------------------------------------------- |
| =        | All                              | Equals                                                           |
| !=       | All                              | Doesn't Equal                                                    |
| IN       | All                              | InShortcut for  queriesValues must be in Array       |
| NIN      | All                              | Not InShortcut for  queriesValues must be in Array |
| >        | IntegerDate (UNIX Timestamp) | Greater than                                                     |
| Date (UNIX Timestamp) | Lower than                                                       |
| ~        | String                           | Contains                                                         |
| !~       | String                           | Doesn't Contain                                                  |
| ^        | String                           | Starts With                                                      |
| $        | String                           | Ends With                                                        |


Endpoint: POST /contacts/search
Version: 2.13
Security: bearerAuth

## Header parameters:

  - `Intercom-Version` (string)
    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", "2.12", "2.13", "Unstable"

## Request fields (application/json):

  - `query` (any, required)

  - `pagination` (object,null)

  - `pagination.per_page` (integer)
    The number of results to fetch per page.
    Example: 2

  - `pagination.starting_after` (string,null)
    The cursor to use in the next request to get the next page of results.
    Example: "your-cursor-from-response"

## Response 200 fields (application/json):

  - `type` (string)
    Always list
    Enum: "list"

  - `data` (array)
    The list of contact objects

  - `data.type` (string)
    The type of object.
    Example: "contact"

  - `data.id` (string)
    The unique identifier for the contact which is given by Intercom.
    Example: "5ba682d23d7cf92bef87bfd4"

  - `data.external_id` (string,null)
    The unique identifier for the contact which is provided by the Client.
    Example: "70"

  - `data.workspace_id` (string)
    The id of the workspace which the contact belongs to.
    Example: "ecahpwf5"

  - `data.role` (string)
    The role of the contact.
    Example: "user"

  - `data.email` (string)
    The contact's email.
    Example: "joe@example.com"

  - `data.email_domain` (string)
    The contact's email domain.
    Example: "example.com"

  - `data.phone` (string,null)
    The contacts phone.
    Example: "+1123456789"

  - `data.name` (string,null)
    The contacts name.
    Example: "John Doe"

  - `data.owner_id` (integer,null)
    The id of an admin that has been assigned account ownership of the contact.
    Example: 123

  - `data.has_hard_bounced` (boolean)
    Whether the contact has had an email sent to them hard bounce.
    Example: true

  - `data.marked_email_as_spam` (boolean)
    Whether the contact has marked an email sent to them as spam.
    Example: true

  - `data.unsubscribed_from_emails` (boolean)
    Whether the contact is unsubscribed from emails.
    Example: true

  - `data.created_at` (integer)
    (UNIX timestamp) The time when the contact was created.
    Example: 1571672154

  - `data.updated_at` (integer)
    (UNIX timestamp) The time when the contact was last updated.
    Example: 1571672154

  - `data.signed_up_at` (integer,null)
    (UNIX timestamp) The time specified for when a contact signed up.
    Example: 1571672154

  - `data.last_seen_at` (integer,null)
    (UNIX timestamp) The time when the contact was last seen (either where the Intercom Messenger was installed or when specified manually).
    Example: 1571672154

  - `data.last_replied_at` (integer,null)
    (UNIX timestamp) The time when the contact last messaged in.
    Example: 1571672154

  - `data.last_contacted_at` (integer,null)
    (UNIX timestamp) The time when the contact was last messaged.
    Example: 1571672154

  - `data.last_email_opened_at` (integer,null)
    (UNIX timestamp) The time when the contact last opened an email.
    Example: 1571672154

  - `data.last_email_clicked_at` (integer,null)
    (UNIX timestamp) The time when the contact last clicked a link in an email.
    Example: 1571672154

  - `data.language_override` (string,null)
    A preferred language setting for the contact, used by the Intercom Messenger even if their browser settings change.
    Example: "en"

  - `data.browser` (string,null)
    The name of the browser which the contact is using.
    Example: "Chrome"

  - `data.browser_version` (string,null)
    The version of the browser which the contact is using.
    Example: "80.0.3987.132"

  - `data.browser_language` (string,null)
    The language set by the browser which the contact is using.
    Example: "en-US"

  - `data.os` (string,null)
    The operating system which the contact is using.
    Example: "Mac OS X"

  - `data.android_app_name` (string,null)
    The name of the Android app which the contact is using.
    Example: "Intercom"

  - `data.android_app_version` (string,null)
    The version of the Android app which the contact is using.
    Example: "5.0.0"

  - `data.android_device` (string,null)
    The Android device which the contact is using.
    Example: "Pixel 3"

  - `data.android_os_version` (string,null)
    The version of the Android OS which the contact is using.
    Example: "10"

  - `data.android_sdk_version` (string,null)
    The version of the Android SDK which the contact is using.
    Example: "28"

  - `data.android_last_seen_at` (integer,null)
    (UNIX timestamp) The time when the contact was last seen on an Android device.
    Example: 1571672154

  - `data.ios_app_name` (string,null)
    The name of the iOS app which the contact is using.
    Example: "Intercom"

  - `data.ios_app_version` (string,null)
    The version of the iOS app which the contact is using.
    Example: "5.0.0"

  - `data.ios_device` (string,null)
    The iOS device which the contact is using.
    Example: "iPhone 11"

  - `data.ios_os_version` (string,null)
    The version of iOS which the contact is using.
    Example: "13.3.1"

  - `data.ios_sdk_version` (string,null)
    The version of the iOS SDK which the contact is using.
    Example: "13.3.1"

  - `data.ios_last_seen_at` (integer,null)
    (UNIX timestamp) The last time the contact used the iOS app.
    Example: 1571672154

  - `data.custom_attributes` (object)
    The custom attributes which are set for the contact.

  - `data.avatar` (object,null)

  - `data.avatar.type` (string)
    The type of object
    Example: "avatar"

  - `data.avatar.image_url` (string,null)
    An image URL containing the avatar of a contact.
    Example: "https://example.org/128Wash.jpg"

  - `data.tags` (object,null)
    An object containing tags meta data about the tags that a contact has. Up to 10 will be displayed here. Use the url to get more.

  - `data.tags.data` (array)
    This object represents the tags attached to a contact.

  - `data.tags.data.type` (string)
    The addressable object type
    Example: "note"

  - `data.tags.data.id` (string)
    The id of the addressable object
    Example: "123"

  - `data.tags.data.url` (string)
    Url to get more company resources for this contact
    Example: "/contacts/5ba682d23d7cf92bef87bfd4/notes"

  - `data.tags.url` (string)
    url to get more tag resources for this contact
    Example: "/contacts/5ba682d23d7cf92bef87bfd4/tags"

  - `data.tags.total_count` (integer)
    Int representing the total number of tags attached to this contact
    Example: 100

  - `data.tags.has_more` (boolean)
    Whether there's more Addressable Objects to be viewed. If true, use the url to view all
    Example: true

  - `data.notes` (object)
    An object containing notes meta data about the notes that a contact has. Up to 10 will be displayed here. Use the url to get more.

  - `data.notes.data` (array)
    This object represents the notes attached to a contact.

  - `data.notes.total_count` (integer)
    Int representing the total number of companyies attached to this contact
    Example: 100

  - `data.companies` (object)
    An object containing companies meta data about the companies that a contact has. Up to 10 will be displayed here. Use the url to get more.

  - `data.companies.data` (array)
    An array of company data objects attached to the contact.

  - `data.companies.data.id` (string)
    The unique identifier for the company which is given by Intercom.
    Example: "5ba682d23d7cf92bef87bfd4"

  - `data.companies.data.type` (string)
    The type of the object. Always company.
    Enum: "company"

  - `data.companies.data.url` (string)
    The relative URL of the company.
    Example: "/companies/5ba682d23d7cf92bef87bfd4"

  - `data.location` (object)
    An object containing location meta data about a Intercom contact.

  - `data.location.type` (string,null)
    Always location
    Example: "location"

  - `data.location.country` (string,null)
    The country that the contact is located in
    Example: "Ireland"

  - `data.location.region` (string,null)
    The overal region that the contact is located in
    Example: "Dublin"

  - `data.location.city` (string,null)
    The city that the contact is located in
    Example: "Dublin"

  - `data.social_profiles` (object)
    An object containing social profiles that a contact has.

  - `data.social_profiles.data` (array)
    A list of social profiles objects associated with the contact.

  - `data.social_profiles.data.type` (string)
    value is "social_profile"
    Example: "social_profile"

  - `data.social_profiles.data.name` (string)
    The name of the Social media profile
    Example: "Facebook"

  - `data.social_profiles.data.url` (string)
    The name of the Social media profile
    Example: "http://twitter.com/th1sland"

  - `total_count` (integer)
    A count of the total number of objects.
    Example: 100

  - `pages` (object,null)
    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.

  - `pages.type` (string)
    the type of object .
    Enum: "pages"

  - `pages.page` (integer)
    The current page
    Example: 1

  - `pages.next` (object,null)

  - `pages.next.per_page` (integer)
    The number of results to fetch per page.
    Example: 2

  - `pages.next.starting_after` (string,null)
    The cursor to use in the next request to get the next page of results.
    Example: "your-cursor-from-response"

  - `pages.per_page` (integer)
    Number of results per page
    Example: 2

  - `pages.total_pages` (integer)
    Total number of pages
    Example: 13

## Response 401 fields (application/json):

  - `type` (string, required)
    The type is error.list
    Example: "error.list"

  - `request_id` (string,null)
    Example: "f93ecfa8-d08a-4325-8694-89aeb89c8f85"

  - `errors` (array, required)
    An array of one or more error objects

  - `errors.code` (string, required)
    A string indicating the kind of error, used to further qualify the HTTP response code
    Example: "unauthorized"

  - `errors.message` (string,null)
    Optional. Human readable description of the error.
    Example: "Access Token Invalid"

  - `errors.field` (string,null)
    Optional. Used to identify a particular field or query parameter that was in error.
    Example: "email"