diff --git a/descriptions/2.10/api.intercom.io.yaml b/descriptions/2.10/api.intercom.io.yaml index 9899675f..20299b94 100644 --- a/descriptions/2.10/api.intercom.io.yaml +++ b/descriptions/2.10/api.intercom.io.yaml @@ -3676,10 +3676,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -3732,24 +3745,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -15848,13 +15863,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.11/api.intercom.io.yaml b/descriptions/2.11/api.intercom.io.yaml index 7fe9f8c1..0f477657 100644 --- a/descriptions/2.11/api.intercom.io.yaml +++ b/descriptions/2.11/api.intercom.io.yaml @@ -3755,10 +3755,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -3811,24 +3824,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -17308,13 +17323,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.12/api.intercom.io.yaml b/descriptions/2.12/api.intercom.io.yaml index 70aac5aa..e2d6e12a 100644 --- a/descriptions/2.12/api.intercom.io.yaml +++ b/descriptions/2.12/api.intercom.io.yaml @@ -4289,10 +4289,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -4345,24 +4358,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -17251,13 +17266,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.13/api.intercom.io.yaml b/descriptions/2.13/api.intercom.io.yaml index d2255784..5655f8b5 100644 --- a/descriptions/2.13/api.intercom.io.yaml +++ b/descriptions/2.13/api.intercom.io.yaml @@ -4810,10 +4810,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -4866,24 +4879,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -18916,13 +18931,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.14/api.intercom.io.yaml b/descriptions/2.14/api.intercom.io.yaml index 2b224f0f..d4c631bb 100644 --- a/descriptions/2.14/api.intercom.io.yaml +++ b/descriptions/2.14/api.intercom.io.yaml @@ -5772,10 +5772,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -5828,24 +5841,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -21567,13 +21582,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.15/api.intercom.io.yaml b/descriptions/2.15/api.intercom.io.yaml index 84f2b72b..e31feab1 100644 --- a/descriptions/2.15/api.intercom.io.yaml +++ b/descriptions/2.15/api.intercom.io.yaml @@ -5695,10 +5695,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -5751,24 +5764,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -22548,13 +22563,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.16/api.intercom.io.yaml b/descriptions/2.16/api.intercom.io.yaml index 5b27176d..df2d4a8d 100644 --- a/descriptions/2.16/api.intercom.io.yaml +++ b/descriptions/2.16/api.intercom.io.yaml @@ -8742,10 +8742,23 @@ paths: ### Searching for Timestamp Fields - All timestamp fields (created_at, updated_at etc.) are filtered by UTC calendar day in Contact Search. An equality (=) query on a timestamp matches any contact whose value falls on the same UTC day, so filtering by a value the API returned reliably matches that contact regardless of your workspace's timezone. Comparisons (>, <) are evaluated at UTC day granularity. - 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 UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. - If you'd like to get contacts created on January 1st, 2020 (UTC) you should search with a created_at value equal (=) to 1577836800 (January 1st, 2020 12:00 AM UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -8799,24 +8812,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -33288,13 +33303,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.7/api.intercom.io.yaml b/descriptions/2.7/api.intercom.io.yaml index 19ea31b9..2a43f6d5 100644 --- a/descriptions/2.7/api.intercom.io.yaml +++ b/descriptions/2.7/api.intercom.io.yaml @@ -3894,10 +3894,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -3950,24 +3963,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -13847,13 +13862,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.8/api.intercom.io.yaml b/descriptions/2.8/api.intercom.io.yaml index d8f84eda..566fbe09 100644 --- a/descriptions/2.8/api.intercom.io.yaml +++ b/descriptions/2.8/api.intercom.io.yaml @@ -3894,10 +3894,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -3950,24 +3963,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -13871,13 +13886,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: diff --git a/descriptions/2.9/api.intercom.io.yaml b/descriptions/2.9/api.intercom.io.yaml index c8e73661..fe8d8ac1 100644 --- a/descriptions/2.9/api.intercom.io.yaml +++ b/descriptions/2.9/api.intercom.io.yaml @@ -3894,10 +3894,23 @@ paths: ### 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. The day a timestamp falls on is determined using your workspace's timezone, so the same query can return different results across workspaces in different timezones. Because timestamps are stored in UTC, filtering by a value the API returned may not match the originating contact when your workspace is not set to UTC. - For example, on a workspace set to UTC, if you search for all Contacts with a created_at value greater (>) than 1577869200 (the UNIX timestamp for January 1st, 2020 9:00 AM UTC), that will be interpreted as 1577836800 (January 1st, 2020 12:00 AM UTC). The search results will then include Contacts created from January 2nd, 2020 12:00 AM UTC onwards. On a workspace in another timezone, the day boundaries fall on that timezone's midnight instead. - 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 UTC). - This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly. + 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 @@ -3950,24 +3963,26 @@ paths: ### Accepted Operators - {% admonition type="warning" name="Searching based on `created_at`" %} - You cannot use the `<=` or `>=` operators to search by `created_at`. + {% 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 (`"="`). 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). + 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. - | Operator | Valid Types | Description | - | :------- | :------------------------------- | :--------------------------------------------------------------- | - | = | All | Equals | - | != | All | Doesn't Equal | - | IN | All | In
Shortcut for `OR` queries
Values must be in Array | - | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | - | > | Integer
Date (UNIX Timestamp) | Greater than | - | < | Integer
Date (UNIX Timestamp) | Lower than | - | ~ | String | Contains | - | !~ | String | Doesn't Contain | - | ^ | String | Starts With | - | $ | String | Ends With | + | 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 | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | responses: '200': description: successful @@ -15224,13 +15239,20 @@ components: - IN - NIN - "<" + - "<=" - ">" + - ">=" - "~" - "!~" - "^" - "$" - description: The accepted operators you can use to define how you want to - search for the value. + 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: + - `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$` + - `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. example: ">" value: oneOf: