Skip to content

Commit 45d61ba

Browse files
adisan19adisan19
authored
Document exact-second timestamp filtering for contacts search on Preview (#627)
1 parent 073804a commit 45d61ba

1 file changed

Lines changed: 49 additions & 33 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 49 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -9063,10 +9063,15 @@ paths:
90639063

90649064
### Searching for Timestamp Fields
90659065

9066-
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.
9067-
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.
9068-
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).
9069-
This behaviour applies only to timestamps used in search queries. The search results will still contain the full UNIX timestamp and be sorted accordingly.
9066+
Standard timestamp fields and Date custom attributes behave differently.
9067+
9068+
**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.
9069+
9070+
**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.
9071+
9072+
**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.
9073+
9074+
Only search queries behave this way. Responses always carry the full UNIX timestamp, and sorting uses the full value.
90709075

90719076
### Accepted Fields
90729077

@@ -9084,14 +9089,14 @@ paths:
90849089
| phone | String |
90859090
| formatted_phone | String |
90869091
| external_id | String |
9087-
| created_at | Date (UNIX Timestamp) |
9088-
| signed_up_at | Date (UNIX Timestamp) |
9089-
| updated_at | Date (UNIX Timestamp) |
9090-
| last_seen_at | Date (UNIX Timestamp) |
9091-
| last_contacted_at | Date (UNIX Timestamp) |
9092-
| last_replied_at | Date (UNIX Timestamp) |
9093-
| last_email_opened_at | Date (UNIX Timestamp) |
9094-
| last_email_clicked_at | Date (UNIX Timestamp) |
9092+
| created_at | Datetime (Unix timestamp in seconds) |
9093+
| signed_up_at | Datetime (Unix timestamp in seconds) |
9094+
| updated_at | Datetime (Unix timestamp in seconds) |
9095+
| last_seen_at | Datetime (Unix timestamp in seconds) |
9096+
| last_contacted_at | Datetime (Unix timestamp in seconds) |
9097+
| last_replied_at | Datetime (Unix timestamp in seconds) |
9098+
| last_email_opened_at | Datetime (Unix timestamp in seconds) |
9099+
| last_email_clicked_at | Datetime (Unix timestamp in seconds) |
90959100
| language_override | String |
90969101
| browser | String |
90979102
| browser_language | String |
@@ -9102,42 +9107,44 @@ paths:
91029107
| unsubscribed_from_emails | Boolean |
91039108
| marked_email_as_spam | Boolean |
91049109
| has_hard_bounced | Boolean |
9105-
| ios_last_seen_at | Date (UNIX Timestamp) |
9110+
| ios_last_seen_at | Datetime (Unix timestamp in seconds) |
91069111
| ios_app_version | String |
91079112
| ios_device | String |
91089113
| ios_app_device | String |
91099114
| ios_os_version | String |
91109115
| ios_app_name | String |
91119116
| ios_sdk_version | String |
9112-
| android_last_seen_at | Date (UNIX Timestamp) |
9117+
| android_last_seen_at | Datetime (Unix timestamp in seconds) |
91139118
| android_app_version | String |
91149119
| android_device | String |
91159120
| android_app_name | String |
91169121
| andoid_sdk_version | String |
91179122
| segment_id | String |
91189123
| tag_id | String |
9119-
| custom_attributes.{attribute_name} | String |
9124+
| custom_attributes.{attribute_name} | Matches the attribute's own type<br>(String, Integer, Float, Boolean or Date) |
91209125

91219126
### Accepted Operators
91229127

9123-
{% admonition type="warning" name="Searching based on `created_at`" %}
9124-
You cannot use the `<=` or `>=` operators to search by `created_at`.
9128+
{% admonition type="warning" name="Operators not supported on Date custom attributes" %}
9129+
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.
91259130
{% /admonition %}
91269131

9127-
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).
9128-
9129-
| Operator | Valid Types | Description |
9130-
| :------- | :------------------------------- | :--------------------------------------------------------------- |
9131-
| = | All | Equals |
9132-
| != | All | Doesn't Equal |
9133-
| IN | All | In<br>Shortcut for `OR` queries<br>Values must be in Array |
9134-
| NIN | All | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
9135-
| > | Integer<br>Date (UNIX Timestamp) | Greater than |
9136-
| < | Integer<br>Date (UNIX Timestamp) | Lower than |
9137-
| ~ | String | Contains |
9138-
| !~ | String | Doesn't Contain |
9139-
| ^ | String | Starts With |
9140-
| $ | String | Ends With |
9132+
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.
9133+
9134+
| Operator | Valid Types | Description |
9135+
| :------- | :---------------------------------- | :----------------------------------------------------------------------|
9136+
| = | All | Equals |
9137+
| != | All except Date | Doesn't Equal<br>Also matches Contacts with no value set |
9138+
| IN | All except Date, Datetime and tag_id | In<br>Shortcut for `OR` queries<br>Values must be in Array |
9139+
| NIN | All except Date, Datetime and tag_id | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
9140+
| > | Integer<br>Datetime<br>Date | Greater than<br>On Date custom attributes, matches from the start of the next day |
9141+
| < | Integer<br>Datetime<br>Date | Lower than<br>On Date custom attributes, matches before the start of the day |
9142+
| >= | Integer<br>Datetime | Greater than or equal to<br>Not supported on Date custom attributes |
9143+
| <= | Integer<br>Datetime | Lower than or equal to<br>Not supported on Date custom attributes |
9144+
| ~ | String | Contains |
9145+
| !~ | String | Doesn't Contain |
9146+
| ^ | String | Starts With |
9147+
| $ | String | Ends With |
91419148
responses:
91429149
'200':
91439150
description: successful
@@ -33980,6 +33987,7 @@ components:
3398033987
- float
3398133988
- boolean
3398233989
- date
33990+
- datetime
3398333991
example: boolean
3398433992
options:
3398533993
type: array
@@ -38964,13 +38972,21 @@ components:
3896438972
- IN
3896538973
- NIN
3896638974
- "<"
38975+
- "<="
3896738976
- ">"
38977+
- ">="
3896838978
- "~"
3896938979
- "!~"
3897038980
- "^"
3897138981
- "$"
38972-
description: The accepted operators you can use to define how you want to
38973-
search for the value.
38982+
description: |-
38983+
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:
38984+
- `string` fields: `=`, `!=`, `IN`, `NIN`, `~`, `!~`, `^`, `$`
38985+
- `tag_id`: `=` and `!=` only. Every other operator returns an error.
38986+
- `boolean` fields: `=`, `!=`, `IN`, `NIN`
38987+
- `integer` fields: `=`, `!=`, `IN`, `NIN`, `<`, `>`, `<=`, `>=`
38988+
- `datetime` fields (standard contact timestamps such as `created_at` and `last_seen_at`): `=`, `!=`, `<`, `>`, `<=`, `>=`. Filtering is on the exact second, in UTC.
38989+
- `date` fields (Date custom attributes): `=`, `<`, `>` only. `!=`, `<=`, and `>=` are not supported and return an error. Values are truncated to a whole UTC day.
3897438990
example: ">"
3897538991
value:
3897638992
oneOf:

0 commit comments

Comments
 (0)