{"command":{"effect":"write","timeoutSeconds":30,"inputSchema":{"type":"object","description":"You can search for multiple contacts by the value of their attributes in order to fetch exactly who you want.\n\nTo search for contacts, you need to send a `POST` request to `https://api.intercom.io/contacts/search`.\n\nThis will accept a query object in the body which will define your filters in order to search for contacts.\n\n{% admonition type=\"warning\" name=\"Optimizing search queries\" %}\n Search queries can be complex, so optimizing them can help the performance of your search.\n Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize\n pagination to limit the number of results returned. The default is `50` results per page.\n See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param.\n{% /admonition %}\n### Merged Contacts\n\nContacts 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.\n\n### Contact Creation Delay\n\nIf 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.\n\n### Nesting & Limitations\n\nYou 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).\nThere are some limitations to the amount of multiple's there can be:\n* There's a limit of max 2 nested filters\n* There's a limit of max 15 filters for each AND or OR group\n* There's a limit of max 15 values in an `IN` or `NIN` array\n* `pagination.per_page` must be between 1 and 150\n\n### Searching for Timestamp Fields\n\nStandard timestamp fields and Date custom attributes behave differently.\n\n**Standard timestamp fields** (`created_at`, `updated_at`, `last_seen_at` etc.) are filtered on the exact second, in UTC. `=` matches only Contacts whose value is that exact second, and `>`, `<`, `>=` and `<=` compare against the exact instant you pass - the value is not rounded or truncated. These fields report a type of `datetime` on the Data Attributes endpoint. Note that `!=` also matches Contacts with no value set for the field.\n\n**Date custom attributes** are matched by calendar day, and the day boundary is always UTC regardless of your workspace's timezone. `=` matches the whole UTC day, `>` matches from the start of the *next* UTC day, and `<` matches everything before the start of that day. The `!=`, `>=`, `<=`, `IN` and `NIN` operators are not supported on these fields and return an error.\n\n**Example.** Searching for `created_at` greater than `1577869200` (January 1st, 2020 9:00 AM UTC) returns Contacts created after that exact instant. Passing the same value for a Date custom attribute truncates it to `1577836800` (January 1st, 2020 12:00 AM UTC), so those results begin from January 2nd, 2020 12:00 AM UTC.\n\nOnly search queries behave this way. Responses always carry the full UNIX timestamp, and sorting uses the full value.\n\n### Accepted Fields\n\nMost 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\"`).\n\n| Field | Type |\n| ---------------------------------- | ------------------------------ |\n| id | String |\n| role | String
Accepts user or lead; contact is treated as lead |\n| name | String |\n| avatar | String |\n| owner_id | Integer |\n| email | String |\n| email_domain | String |\n| phone | String |\n| external_id | String |\n| created_at | Datetime (Unix timestamp in seconds) |\n| signed_up_at | Datetime (Unix timestamp in seconds) |\n| updated_at | Datetime (Unix timestamp in seconds) |\n| last_seen_at | Datetime (Unix timestamp in seconds) |\n| last_contacted_at | Datetime (Unix timestamp in seconds) |\n| last_replied_at | Datetime (Unix timestamp in seconds) |\n| last_email_opened_at | Datetime (Unix timestamp in seconds) |\n| last_email_clicked_at | Datetime (Unix timestamp in seconds) |\n| language_override | String |\n| browser | String |\n| browser_version | String |\n| browser_language | String |\n| os | String |\n| location.country | String |\n| location.region | String |\n| location.city | String |\n| unsubscribed_from_emails | Boolean |\n| marked_email_as_spam | Boolean |\n| has_hard_bounced | Boolean |\n| phone_country | String |\n| slack_email | String |\n| fin_qualification_status | String |\n| whatsapp_number | String
Only on workspaces with the WhatsApp integration |\n| ios_last_seen_at | Datetime (Unix timestamp in seconds) |\n| ios_app_version | String |\n| ios_device | String |\n| ios_os_version | String |\n| ios_app_name | String |\n| ios_sdk_version | String |\n| android_last_seen_at | Datetime (Unix timestamp in seconds) |\n| android_app_version | String |\n| android_device | String |\n| android_os_version | String |\n| android_app_name | String |\n| android_sdk_version | String |\n| enabled_push_messaging | Boolean |\n| segment_id | String |\n| tag_id | String |\n| custom_attributes.{attribute_name} | Matches the attribute's own type
(String, Integer, Float, Boolean or Date) |\n\nThe `ios_*` fields other than `ios_app_name` are searchable only once your workspace has been set up for the Intercom iOS SDK or has received a request from it, and the `android_*` fields other than `android_app_name` only once the same is true for the Android SDK. `enabled_push_messaging` needs either. Until then, they return an `invalid_field` error.\n\n### Accepted Operators\n\n{% admonition type=\"warning\" name=\"Operators not supported on Date custom attributes\" %}\n Date custom attributes do not support the `!=`, `>=`, or `<=` operators. Using them returns a `422` error. Standard timestamp fields (`created_at`, `updated_at` etc.) do support these operators, and are filtered on the exact second.\n{% /admonition %}\n\nThe 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` or `segment_id` supports only the `=` and `!=` operators, with a single ID string as the value.\n\nA `null` value is accepted only with `=` (matches Contacts with no value set) and `!=` (matches Contacts with any value set). An array value is accepted only with `IN` and `NIN`. String values must be shorter than 256 characters.\n\n| Operator | Valid Types | Description |\n| :------- | :---------------------------------- | :----------------------------------------------------------------------|\n| = | All | Equals |\n| != | All except Date | Doesn't Equal
Also matches Contacts with no value set |\n| IN | All except Date, Datetime, tag_id and segment_id | In
Shortcut for `OR` queries
Values must be in Array |\n| NIN | All except Date, Datetime, tag_id and segment_id | Not In
Shortcut for `OR !` queries
Values must be in Array |\n| > | Integer
Float
Datetime
Date | Greater than
On Date custom attributes, matches from the start of the next day |\n| < | Integer
Float
Datetime
Date | Lower than
On Date custom attributes, matches before the start of the day |\n| >= | Integer
Float
Datetime | Greater than or equal to
Not supported on Date custom attributes |\n| <= | Integer
Float
Datetime | Lower than or equal to
Not supported on Date custom attributes |\n| ~ | String | Contains |\n| !~ | String | Doesn't Contain |\n| ^ | String | Starts With |\n| $ | String | Ends With |\n\nRequires the `read_users_companies` or `read_write_users` OAuth scope.\n","properties":{"headers":{"type":"object","properties":{"Intercom-Version":{"$ref":"#/definitions/intercom_version","enum":["2.17"]}},"required":[],"additionalProperties":false},"query":{"type":"object","properties":{"include_merge_history":{"type":"boolean","default":false,"description":"Pass `true` in the query string to include a `merge_history` array on each contact in the response; a JSON boolean in the request body is ignored. Returned for contacts of any role, with at most the 10 most recent merges."},"escape_identity":{"type":"boolean","default":true,"description":"By default, `name` and `email` values in the response, including nested ones such as social profile names, are HTML-escaped (for example, `&` is returned as `&`). Custom attributes and tags are never escaped. Pass `false` to return them unescaped."}},"required":[],"additionalProperties":false},"body":{"$ref":"#/definitions/contact_search_request","examples":[{"query":{"operator":"AND","value":[{"field":"created_at","operator":">","value":"1306054154"}]},"sort":{"field":"created_at","order":"ascending"},"pagination":{"per_page":5}}]}},"required":[],"additionalProperties":false,"definitions":{"intercom_version":{"description":"Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.","type":"string","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","2.14","2.15","2.16","2.17"],"examples":["2.17"]},"contact_search_request":{"description":"Search for contacts using Intercom's Search API.","type":"object","title":"Contact search request","properties":{"query":{"oneOf":[{"$ref":"#/definitions/single_filter_search_request"},{"$ref":"#/definitions/multiple_filter_search_request"}]},"pagination":{"$ref":"#/definitions/starting_after_paging"},"sort":{"type":"object","description":"An optional object to sort the results by.","properties":{"field":{"type":"string","description":"The field to sort the results on.","examples":["created_at"]},"order":{"type":"string","description":"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`.","enum":["ascending","descending"],"default":"descending","examples":["descending"]}}}},"required":["query"]},"single_filter_search_request":{"title":"Single Filter Search Request","description":"Search using Intercoms Search APIs with a single filter.","type":"object","properties":{"field":{"type":"string","description":"The accepted field that you want to search on.","examples":["created_at"]},"operator":{"type":"string","enum":["=","!=","IN","NIN","<","<=",">",">=","~","!~","^","$"],"description":"The accepted operators you can use to define how you want to search for the value. Operator support depends on the field's data type. The breakdown below is for Contacts search; the other search endpoints that share this schema accept a different set per field:\n- `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$`\n- `tag_id`: `=` and `!=` only. Every other operator returns an error.\n- `boolean` fields: `=`, `!=`, `IN`, `NIN`\n- `integer` fields: `=`, `!=`, `IN`, `NIN`, `<`, `>`, `<=`, `>=`\n- `datetime` fields (standard contact timestamps such as `created_at` and `last_seen_at`): `=`, `!=`, `<`, `>`, `<=`, `>=`. Filtering is on the exact second, in UTC.\n- `date` fields (Date custom attributes): `=`, `<`, `>` only. `!=`, `<=`, and `>=` are not supported and return an error. Values are truncated to a whole UTC day.","examples":[">"]},"value":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"boolean"},{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"integer"}]}}],"description":"The value that you want to search on.","examples":["73732934"]}}},"multiple_filter_search_request":{"title":"Multiple Filter Search Request","description":"Search using Intercoms Search APIs with more than one filter.","type":"object","properties":{"operator":{"type":"string","enum":["AND","OR"],"description":"An operator to allow boolean inspection between multiple fields.","examples":["AND"]},"value":{"oneOf":[{"type":"array","description":"Add mutiple filters.","title":"multiple filter search request","items":{"$ref":"#/definitions/multiple_filter_search_request"}},{"type":"array","description":"Add a single filter field.","title":"single filter search request","items":{"$ref":"#/definitions/single_filter_search_request"}}]}}},"starting_after_paging":{"title":"Pagination: Starting After","type":["object","null"],"properties":{"per_page":{"type":"integer","description":"The number of results to fetch per page.","examples":[2]},"starting_after":{"type":["string","null"],"description":"The cursor to use in the next request to get the next page of results.","examples":["your-cursor-from-response"]}}}}},"name":"Search contacts","id":"intercom.searchcontacts","example":{},"maxRequests":1,"summary":false}}