From 018b188fee22023ec97d3b46d917959ca19b217f Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Wed, 21 Oct 2026 16:25:56 +0100 Subject: [PATCH 1/2] Correct the ticket search fields, sorting and page size Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 13 ++++++++----- descriptions/2.17/api.intercom.io.yaml | 17 ++++++++++------- 2 files changed, 18 insertions(+), 12 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index dcbc3ebd..5cc09d25 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -27528,7 +27528,7 @@ paths: {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize - pagination to limit the number of results returned. The default is `20` results per page. + pagination to limit the number of results returned. The default is `20` results per page and maximum is `150`. See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param. {% /admonition %} @@ -27542,19 +27542,18 @@ paths: ### Accepted Fields Most keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `"foobar"`). - The `source.body` field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a `"I need support"` body - the query should contain a `=` operator with the value `"support"` for such conversation to be returned. A query with a `=` operator and a `"need support"` value will not yield a result. + Fields not in the table below, such as `source.body`, are rejected with a `400` error. | Field | Type | | :---------------------------------------- | :--------------------------------------------------------------------------------------- | - | id | String | + | id | Integer | | created_at | Date (Unix timestamp in seconds) | | updated_at | Date (Unix timestamp in seconds) | | title | String | | description | String | | category | String | - | ticket_type_id | String | + | ticket_type_id | Integer | | contact_ids | String | - | teammate_ids | String | | admin_assignee_id | Integer | | team_assignee_id | Integer | | open | Boolean | @@ -27569,6 +27568,10 @@ paths: * For **Tracker** category tickets, use the term `tracker`. {% /admonition %} + ### Sorting + + You can sort the results with a `sort` object, for example `{"field": "created_at", "order": "ascending"}`. `field` must be one of the fields in the table above, other than `ticket_attribute.{id}`. `order` is `ascending` or `descending`, and any other value is treated as `descending`. Without `sort`, results are sorted by `updated_at`, newest first. + ### Accepted Operators {% admonition type="info" name="Searching based on `created_at`" %} diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 46f3a062..0df768ab 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -24564,7 +24564,7 @@ paths: {% admonition type="warning" name="Optimizing search queries" %} Search queries can be complex, so optimizing them can help the performance of your search. Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize - pagination to limit the number of results returned. The default is `20` results per page. + pagination to limit the number of results returned. The default is `20` results per page and maximum is `150`. See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#example-search-conversations-request) for more details on how to use the `starting_after` param. {% /admonition %} @@ -24578,21 +24578,20 @@ paths: ### Accepted Fields Most keys listed as part of the Ticket model are searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as `created_at` accepts a date, the `value` cannot be a string such as `"foobar"`). - The `source.body` field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a `"I need support"` body - the query should contain a `=` operator with the value `"support"` for such conversation to be returned. A query with a `=` operator and a `"need support"` value will not yield a result. + Fields not in the table below, such as `source.body`, are rejected with a `400` error. | Field | Type | | :---------------------------------------- | :--------------------------------------------------------------------------------------- | - | id | String | + | id | Integer | | created_at | Date (UNIX timestamp) | | updated_at | Date (UNIX timestamp) | | title | String | | description | String | | category | String | - | ticket_type_id | String | + | ticket_type_id | Integer | | contact_ids | String | - | teammate_ids | String | - | admin_assignee_id | String | - | team_assignee_id | String | + | admin_assignee_id | Integer | + | team_assignee_id | Integer | | open | Boolean | | state | String | | snoozed_until | Date (UNIX timestamp) | @@ -24605,6 +24604,10 @@ paths: * For **Tracker** category tickets, use the term `tracker`. {% /admonition %} + ### Sorting + + You can sort the results with a `sort` object, for example `{"field": "created_at", "order": "ascending"}`. `field` must be one of the fields in the table above, other than `ticket_attribute.{id}`. `order` is `ascending` or `descending`, and any other value is treated as `descending`. Without `sort`, results are sorted by `updated_at`, newest first. + ### Accepted Operators {% admonition type="info" name="Searching based on `created_at`" %} From d20d061165962b4559929b4efe123c72dfa14e41 Mon Sep 17 00:00:00 2001 From: yasser-aboelgheit-intercom Date: Wed, 21 Oct 2026 16:48:59 +0100 Subject: [PATCH 2/2] Exclude title and description from ticket search sort fields Co-Authored-By: Claude Opus 5.5 (1M context) --- descriptions/0/api.intercom.io.yaml | 2 +- descriptions/2.17/api.intercom.io.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 5cc09d25..a48124d1 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -27570,7 +27570,7 @@ paths: ### Sorting - You can sort the results with a `sort` object, for example `{"field": "created_at", "order": "ascending"}`. `field` must be one of the fields in the table above, other than `ticket_attribute.{id}`. `order` is `ascending` or `descending`, and any other value is treated as `descending`. Without `sort`, results are sorted by `updated_at`, newest first. + You can sort the results with a `sort` object, for example `{"field": "created_at", "order": "ascending"}`. `field` must be one of the fields in the table above, other than `ticket_attribute.{id}`, `title` and `description`. `order` is `ascending` or `descending`, and any other value is treated as `descending`. Without `sort`, results are sorted by `updated_at`, newest first. ### Accepted Operators diff --git a/descriptions/2.17/api.intercom.io.yaml b/descriptions/2.17/api.intercom.io.yaml index 0df768ab..ad0b77d2 100644 --- a/descriptions/2.17/api.intercom.io.yaml +++ b/descriptions/2.17/api.intercom.io.yaml @@ -24606,7 +24606,7 @@ paths: ### Sorting - You can sort the results with a `sort` object, for example `{"field": "created_at", "order": "ascending"}`. `field` must be one of the fields in the table above, other than `ticket_attribute.{id}`. `order` is `ascending` or `descending`, and any other value is treated as `descending`. Without `sort`, results are sorted by `updated_at`, newest first. + You can sort the results with a `sort` object, for example `{"field": "created_at", "order": "ascending"}`. `field` must be one of the fields in the table above, other than `ticket_attribute.{id}`, `title` and `description`. `order` is `ascending` or `descending`, and any other value is treated as `descending`. Without `sort`, results are sorted by `updated_at`, newest first. ### Accepted Operators