diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index cfa7184f..b502109d 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -10161,23 +10161,15 @@ paths: ### 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. + Standard timestamp fields and Date custom attributes behave differently. - The day boundary uses **your workspace's timezone**, so the same query can return different results on two workspaces in different timezones. + **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. - Because the value is truncated to a day: + **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. - * `=` 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. + **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. - 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. + Only search queries behave this way. Responses always carry the full UNIX timestamp, and sorting uses the full value. ### Accepted Fields @@ -10195,14 +10187,14 @@ paths: | phone | String | | formatted_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) | + | created_at | Datetime (Unix timestamp in seconds) | + | signed_up_at | Datetime (Unix timestamp in seconds) | + | updated_at | Datetime (Unix timestamp in seconds) | + | last_seen_at | Datetime (Unix timestamp in seconds) | + | last_contacted_at | Datetime (Unix timestamp in seconds) | + | last_replied_at | Datetime (Unix timestamp in seconds) | + | last_email_opened_at | Datetime (Unix timestamp in seconds) | + | last_email_clicked_at | Datetime (Unix timestamp in seconds) | | language_override | String | | browser | String | | browser_language | String | @@ -10213,26 +10205,26 @@ paths: | unsubscribed_from_emails | Boolean | | marked_email_as_spam | Boolean | | has_hard_bounced | Boolean | - | ios_last_seen_at | Date (UNIX Timestamp) | + | ios_last_seen_at | Datetime (Unix timestamp in seconds) | | 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_last_seen_at | Datetime (Unix timestamp in seconds) | | 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 | + | custom_attributes.{attribute_name} | Matches the attribute's own type
(String, Integer, Float, Boolean or Date) | ### 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 type="warning" name="Operators not supported on Date custom attributes" %} + Date custom attributes do not support the `!=`, `>=`, or `<=` operators. Using them returns an error. Standard timestamp fields (`created_at`, `updated_at` etc.) do support these operators, and are filtered on the exact second. {% /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. @@ -10240,13 +10232,13 @@ paths: | Operator | Valid Types | Description | | :------- | :---------------------------------- | :----------------------------------------------------------------------| | = | All | Equals | - | != | All except Date | Doesn't Equal | - | IN | All except Date and tag_id | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All except Date and tag_id | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date | Greater than
On Date fields, matches from the start of the next day | - | < | Integer
Date | Lower than
On Date fields, matches before the start of the day | - | >= | Integer | Greater than or equal to
Not supported on Date fields | - | <= | Integer | Lower than or equal to
Not supported on Date fields | + | != | All except Date | Doesn't Equal
Also matches Contacts with no value set | + | IN | All except Date, Datetime and tag_id | In
Shortcut for `OR` queries
Values must be in Array | + | NIN | All except Date, Datetime and tag_id | Not In
Shortcut for `OR !` queries
Values must be in Array | + | > | Integer
Datetime
Date | Greater than
On Date custom attributes, matches from the start of the next day | + | < | Integer
Datetime
Date | Lower than
On Date custom attributes, matches before the start of the day | + | >= | Integer
Datetime | Greater than or equal to
Not supported on Date custom attributes | + | <= | Integer
Datetime | Lower than or equal to
Not supported on Date custom attributes | | ~ | String | Contains | | !~ | String | Doesn't Contain | | ^ | String | Starts With | @@ -33898,6 +33890,7 @@ components: - float - boolean - date + - datetime example: boolean options: type: array @@ -38734,7 +38727,8 @@ components: - `tag_id`: `=` and `!=` only. Every other operator returns an error. - `boolean` fields: `=`, `!=`, `IN`, `NIN` - `integer` fields: `=`, `!=`, `IN`, `NIN`, `<`, `>`, `<=`, `>=` - - `date` fields (all standard timestamp attributes and date custom attributes): `=`, `<`, `>` only. `!=`, `<=`, `>=`, `IN`, and `NIN` are not supported and return an error. + - `datetime` fields (standard contact timestamps such as `created_at` and `last_seen_at`): `=`, `!=`, `<`, `>`, `<=`, `>=`. Filtering is on the exact second, in UTC. + - `date` fields (Date custom attributes): `=`, `<`, `>` only. `!=`, `<=`, and `>=` are not supported and return an error. Values are truncated to a whole UTC day. example: ">" value: oneOf: