From e9752fb22756bf3cbe603f373c19878daf8b89ad Mon Sep 17 00:00:00 2001 From: cox512 Date: Mon, 20 Jul 2026 15:05:14 -0500 Subject: [PATCH 1/3] Add POST /companies/search (Preview) to OpenAPI spec Generated via the generate-openapi-from-pr workflow from intercom/intercom PR #543548. Documents the Preview /companies/search operation, reusing the shared search_request and company_list schemas. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01Wgii8RHNriTrY4QtaJ4UDk --- descriptions/0/api.intercom.io.yaml | 129 ++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 66eb1ed9..e2dba93e 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -6252,6 +6252,135 @@ paths: summary: Company not found value: body: Hello + "/companies/search": + post: + summary: Search companies + parameters: + - name: Intercom-Version + in: header + schema: + "$ref": "#/components/schemas/intercom_version" + tags: + - Companies + operationId: searchCompanies + description: | + You can search for companies by the value of their attributes in order to fetch exactly the companies you want. + + To search for companies, send a `POST` request to `https://api.intercom.io/companies/search`, with a query object in the body defining your filters. + + Note that the API does not include companies who have no associated users in search results. + + {% 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 `15` results per page. + 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 %} + + ### Nesting & Limitations + + You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4). + There are some limitations to the amount of multiple's there can be: + * There's a limit of max 2 nested filters + * There's a limit of max 15 filters for each AND or OR group + + ### Accepted Fields + + Most keys listed as part of the Companies Model are searchable. 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"`). + + | Field | Type | + | ---------------------------------- | ------------------------------ | + | company_id | String | + | name | String | + | created_at | Date (UNIX Timestamp) | + | updated_at | Date (UNIX Timestamp) | + | remote_created_at | Date (UNIX Timestamp) | + | last_request_at | Date (UNIX Timestamp) | + | monthly_spend | Integer | + | session_count | Integer | + | user_count | Integer | + | tag_id | String | + | custom_attributes.{attribute_name} | String | + + ### Accepted Operators + + 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). Searching by `tag_id` supports only the `=` and `!=` operators. + + | Operator | Valid Types | Description | + | :------- | :------------------------------- | :--------------------------------------------------------------- | + | = | All | Equals | + | != | All | Doesn't Equal | + | IN | All | In
Shortcut for `OR` queries
Values must be in Array | + | NIN | All | Not In
Shortcut for `OR !` queries
Values must be in Array | + | > | Integer
Date (UNIX Timestamp) | Greater than | + | < | Integer
Date (UNIX Timestamp) | Lower than | + | ~ | String | Contains | + | !~ | String | Doesn't Contain | + | ^ | String | Starts With | + | $ | String | Ends With | + responses: + '200': + description: successful + content: + application/json: + examples: + successful: + value: + type: list + data: [] + total_count: 0 + pages: + type: pages + page: 1 + per_page: 15 + total_pages: 0 + schema: + "$ref": "#/components/schemas/company_list" + '401': + description: Unauthorized + content: + application/json: + examples: + Unauthorized: + value: + type: error.list + request_id: f0dc95f1-9e46-4e8d-8150-89365c2c5195 + errors: + - code: unauthorized + message: Access Token Invalid + schema: + "$ref": "#/components/schemas/error" + '400': + description: Bad Request + content: + application/json: + examples: + Unsupported field: + value: + type: error.list + request_id: 8d6c1f0a-3b2e-4a17-9c5d-1f0e2a3b4c5d + errors: + - code: invalid_field + message: "segment_id is not a valid search field" + schema: + "$ref": "#/components/schemas/error" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/search_request" + examples: + successful: + summary: successful + value: + query: + operator: AND + value: + - field: name + operator: "=" + value: my-company + pagination: + per_page: 5 "/companies/list": post: summary: List all companies From e69864aa43d8d1ce09a5245906a88f61f91bb1b4 Mon Sep 17 00:00:00 2001 From: cox512 Date: Thu, 23 Jul 2026 13:56:50 -0500 Subject: [PATCH 2/3] Sync companies/search 200 example per_page with request example The request example sets pagination.per_page: 5, but the paired 200 response example showed per_page: 15. Match them (5) so request/response example pairs agree, consistent with /contacts/search. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01ATc7UmfbqPvfcrHccXaMPA --- descriptions/0/api.intercom.io.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index e2dba93e..71b91692 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -6332,7 +6332,7 @@ paths: pages: type: pages page: 1 - per_page: 15 + per_page: 5 total_pages: 0 schema: "$ref": "#/components/schemas/company_list" From 321c7929196260ce9029d7c3c7bee5fd7b38614d Mon Sep 17 00:00:00 2001 From: cox512 Date: Thu, 23 Jul 2026 14:27:34 -0500 Subject: [PATCH 3/3] Document sort, plan.* rejection for POST /companies/search Companies search accepts a sort object (validated server-side in intercom/intercom#543548) but referenced the shared search_request schema, which has no sort property. Add a company_search_request schema mirroring contact_search_request, point the operation at it, and document the sort object plus the tag_id filter-only-for-sort caveat. Also call out that plan.id/plan.name are not searchable and return 400 invalid_field. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01ATc7UmfbqPvfcrHccXaMPA --- descriptions/0/api.intercom.io.yaml | 44 ++++++++++++++++++++++++++++- 1 file changed, 43 insertions(+), 1 deletion(-) diff --git a/descriptions/0/api.intercom.io.yaml b/descriptions/0/api.intercom.io.yaml index 71b91692..5bfd0cd3 100644 --- a/descriptions/0/api.intercom.io.yaml +++ b/descriptions/0/api.intercom.io.yaml @@ -6302,6 +6302,8 @@ paths: | tag_id | String | | custom_attributes.{attribute_name} | String | + The `plan.id` and `plan.name` fields are not searchable and return a `400` error with code `invalid_field`. + ### Accepted Operators 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). Searching by `tag_id` supports only the `=` and `!=` operators. @@ -6318,6 +6320,10 @@ paths: | !~ | String | Doesn't Contain | | ^ | String | Starts With | | $ | String | Ends With | + + ### Sorting + + Pass an optional `sort` object with a `field` and an `order` (`ascending` or `descending`; defaults to `descending`) to order the results. An invalid `order` returns a `400` error with code `invalid_sort_order`. `tag_id` can be used as a filter but not as a sort field. responses: '200': description: successful @@ -6368,7 +6374,7 @@ paths: content: application/json: schema: - "$ref": "#/components/schemas/search_request" + "$ref": "#/components/schemas/company_search_request" examples: successful: summary: successful @@ -6379,6 +6385,9 @@ paths: - field: name operator: "=" value: my-company + sort: + field: name + order: ascending pagination: per_page: 5 "/companies/list": @@ -36549,6 +36558,39 @@ components: "$ref": "#/components/schemas/starting_after_paging" required: - query + company_search_request: + description: Search for companies using Intercom's Search API. + type: object + title: Company 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 segment: title: Segment type: object