Skip to content

Document exact-second timestamp filtering for contacts search on Preview #627

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 3 commits into from
Aug 19, 2026
+49 −33
Merged

Document exact-second timestamp filtering for contacts search on Preview #627

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
53c5ce8
Document exact-second timestamp filtering for contacts search on Preview
adisan19 Aug 19, 2026
606fcef
Leave float out of the operator docs
adisan19 Aug 19, 2026
2fc17db
Match the merged developer-docs Preview contacts search date docs
adisan19 Aug 19, 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
82 changes: 49 additions & 33 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9063,10 +9063,15 @@ 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.
Standard timestamp fields and Date custom attributes behave differently.

**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.

**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.

**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.

Only search queries behave this way. Responses always carry the full UNIX timestamp, and sorting uses the full value.

### Accepted Fields

Expand All @@ -9084,14 +9089,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 @@ -9102,42 +9107,44 @@ 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="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 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 (`"="`). 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).

| Operator | Valid Types | Description |
| :------- | :------------------------------- | :--------------------------------------------------------------- |
| = | All | Equals |
| != | All | Doesn't Equal |
| IN | All | In<br>Shortcut for `OR` queries<br>Values must be in Array |
| NIN | All | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
| > | Integer<br>Date (UNIX Timestamp) | Greater than |
| < | Integer<br>Date (UNIX Timestamp) | Lower than |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
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<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 |
| $ | String | Ends With |
responses:
'200':
description: successful
Expand Down Expand Up @@ -33980,6 +33987,7 @@ components:
- float
- boolean
- date
- datetime
example: boolean
options:
type: array
Expand Down Expand Up @@ -38964,13 +38972,21 @@ 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`, `<`, `>`, `<=`, `>=`
- `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