From e9752fb22756bf3cbe603f373c19878daf8b89ad Mon Sep 17 00:00:00 2001 From: cox512 Date: Mon, 20 Jul 2026 15:05:14 -0500 Subject: [PATCH] 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 66eb1ed..e2dba93 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