Skip to content

Correct contact search date filtering and operator docs #625

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 8 commits into from
Aug 19, 2026
Merged

Correct contact search date filtering and operator docs #625

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
93e5727
Correct contacts search operator docs for date fields
adisan19 Aug 17, 2026
7b1d125
Correct the date-filter error code and the 2.16 day-boundary wording
adisan19 Aug 19, 2026
d6d5031
Split standard timestamps from Date custom attributes in the search d…
adisan19 Aug 19, 2026
cd811f9
Break the search timestamp guidance into readable paragraphs
adisan19 Aug 19, 2026
78db1c2
Stop documenting tag_id as accepting the full set of string operators
adisan19 Aug 19, 2026
71921b5
Drop the Preview version changes; they ship in a separate PR
adisan19 Aug 19, 2026
e57eddb
Leave float out of the operator docs
adisan19 Aug 19, 2026
0906f08
Match the merged developer-docs contacts search date filtering 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
64 changes: 43 additions & 21 deletions descriptions/2.10/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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<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 |
| 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 |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
responses:
'200':
description: successful
Expand Down Expand Up @@ -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:
Expand Down
64 changes: 43 additions & 21 deletions descriptions/2.11/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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<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 |
| 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 |
| ~ | String | Contains |
| !~ | String | Doesn't Contain |
| ^ | String | Starts With |
| $ | String | Ends With |
responses:
'200':
description: successful
Expand Down Expand Up @@ -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:
Expand Down
Loading