Add 400 response for invalid sort.order on POST /contacts/search (#567)

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dan0505

descriptions/0/api.intercom.io.yaml

@@ -8391,11 +8391,25 @@ 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
+                    request_id: 8d6c1f0a-3b2e-4a17-9c5d-1f0e2a3b4c5d
+                    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:
             schema:
-              "$ref": "#/components/schemas/search_request"
+              "$ref": "#/components/schemas/contact_search_request"
             examples:
               successful:
                 summary: successful
@@ -8406,6 +8420,9 @@ paths:
                     - field: created_at
                       operator: ">"
                       value: '1306054154'
+                  sort:
+                    field: created_at
+                    order: ascending
                   pagination:
                     per_page: 5
   "/contacts":
@@ -27497,6 +27514,39 @@ 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. Values other than `ascending` or `descending` return a
+                `400` error with code `invalid_sort_order`.
+              enum:
+              - ascending
+              - descending
+              default: descending
+              example: descending
+      required:
+      - query
     contact_segments:
       title: Segments
       type: object