Skip to content

Document exact-second UTC timestamp filtering for contacts search on 2.17 #733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adisan19 merged 2 commits into from
Oct 16, 2026
Merged

Document exact-second UTC timestamp filtering for contacts search on 2.17 #733

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
626b1ee
Document UTC exact-second contact search timestamps in 2.17
adisan19 Oct 16, 2026
ef077bf
Add datetime to 2.17 data_attribute data_type enum
adisan19 Oct 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 28 additions & 34 deletions descriptions/2.17/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |
Expand All @@ -10213,40 +10205,40 @@ 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<br>(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.

| Operator | Valid Types | Description |
| :------- | :---------------------------------- | :----------------------------------------------------------------------|
| = | All | Equals |
| != | All except Date | Doesn't Equal |
| IN | All except Date and tag_id | In<br>Shortcut for `OR` queries<br>Values must be in Array |
| NIN | All except Date and tag_id | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
| > | Integer<br>Date | Greater than<br>On Date fields, matches from the start of the next day |
| < | Integer<br>Date | Lower than<br>On Date fields, matches before the start of the day |
| >= | Integer | Greater than or equal to<br>Not supported on Date fields |
| <= | Integer | Lower than or equal to<br>Not supported on Date fields |
| != | All except Date | Doesn't Equal<br>Also matches Contacts with no value set |
| IN | All except Date, Datetime and tag_id | In<br>Shortcut for `OR` queries<br>Values must be in Array |
| NIN | All except Date, Datetime and tag_id | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
| > | Integer<br>Datetime<br>Date | Greater than<br>On Date custom attributes, matches from the start of the next day |
| < | Integer<br>Datetime<br>Date | Lower than<br>On Date custom attributes, matches before the start of the day |
| >= | Integer<br>Datetime | Greater than or equal to<br>Not supported on Date custom attributes |
| <= | Integer<br>Datetime | Lower than or equal to<br>Not supported on Date custom attributes |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
Expand Down Expand Up @@ -33898,6 +33890,7 @@ components:
- float
- boolean
- date
- datetime
example: boolean
options:
type: array
Expand Down Expand Up @@ -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:
Expand Down
Loading