From bae73f7de808801b333e92a2dc91809c1c6fc71c Mon Sep 17 00:00:00 2001 From: dq Date: Thu, 25 Jun 2026 12:07:43 +0100 Subject: [PATCH 1/3] Add 400 response for invalid sort.order on POST /contacts/search The contacts search endpoint now returns 400 with an invalid_sort_order error when sort.order is not "ascending" or "descending". Co-Authored-By: Claude Opus 4.8 (1M context) --- descriptions/0/api.intercom.io.yaml | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 9eb99ec..3689308 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -8370,6 +8370,19 @@ paths: message: Access Token Invalid schema: "$ref": "#/components/schemas/error" + '400': + description: Bad Request + content: + application/json: + examples: + Invalid sort order: + value: + type: error.list + errors: + - code: invalid_sort_order + message: "Invalid sort order 'desc'. Must be one of: ascending, descending" + schema: + "$ref": "#/components/schemas/error" requestBody: content: application/json: From 1d08c79a1d9865e075a7bf1c9a27babf6c48220f Mon Sep 17 00:00:00 2001 From: dq Date: Thu, 25 Jun 2026 14:30:04 +0100 Subject: [PATCH 2/3] Document contacts search sort schema and align 400 example - Add a contact_search_request schema (sort.field + sort.order enum: ascending/descending, default descending) and point POST /contacts/search at it. Conversations and tickets searches keep the shared search_request. - Add request_id to the 400 invalid_sort_order example for parity with the rest of the spec. Co-Authored-By: Claude Opus 4.8 (1M context) --- descriptions/0/api.intercom.io.yaml | 38 ++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 3689308..829522c 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -8378,6 +8378,7 @@ paths: Invalid sort order: value: type: error.list + request_id: 8d6c1f0a-3b2e-4a17-9c5d-1f0e2a3b4c5d errors: - code: invalid_sort_order message: "Invalid sort order 'desc'. Must be one of: ascending, descending" @@ -8387,7 +8388,7 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/search_request" + "$ref": "#/components/schemas/contact_search_request" examples: successful: summary: successful @@ -8398,6 +8399,9 @@ paths: - field: created_at operator: ">" value: '1306054154' + sort: + field: created_at + order: ascending pagination: per_page: 5 "/contacts": @@ -27489,6 +27493,38 @@ components: maxItems: 10 required: - user_id + contact_search_request: + description: Search for contacts using Intercom's Search API. + type: object + title: Contact search request + properties: + query: + oneOf: + - "$ref": "#/components/schemas/single_filter_search_request" + title: Single filter search request + - "$ref": "#/components/schemas/multiple_filter_search_request" + title: multiple filter search request + pagination: + "$ref": "#/components/schemas/starting_after_paging" + sort: + type: object + description: An optional object to sort the results by. + properties: + field: + type: string + description: The field to sort the results on. + example: created_at + order: + type: string + description: The order to sort the results in. Defaults to `descending` + when omitted. Any other value returns a `400` error with code `invalid_sort_order`. + enum: + - ascending + - descending + default: descending + example: descending + required: + - query contact_segments: title: Segments type: object From 8bf1d9936d4dfd93056e524a34f625e76de20b58 Mon Sep 17 00:00:00 2001 From: dq Date: Thu, 25 Jun 2026 15:01:10 +0100 Subject: [PATCH 3/3] Clarify sort.order description on contact_search_request Reword so valid values aren't implied to 400: "Values other than `ascending` or `descending` return a 400 error" instead of "Any other value". Keeps the contacts search schema in sync with developer-docs. Co-Authored-By: Claude Opus 4.8 (1M context) --- descriptions/0/api.intercom.io.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 829522c..2d60599 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -27517,7 +27517,8 @@ components: order: type: string description: The order to sort the results in. Defaults to `descending` - when omitted. Any other value returns a `400` error with code `invalid_sort_order`. + when omitted. Values other than `ascending` or `descending` return a + `400` error with code `invalid_sort_order`. enum: - ascending - descending