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