Skip to content

Commit fd21161

Browse files
cox512claude
cox512
and
claude
authored
Add POST /companies/search (Preview) (#599)
* 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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Wgii8RHNriTrY4QtaJ4UDk * 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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ATc7UmfbqPvfcrHccXaMPA * 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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ATc7UmfbqPvfcrHccXaMPA * Correct IN/NIN operator validity in company search docs IN and NIN are rejected for Date fields and for tag_id (tags allow only = and !=), so the operator table's "All" was inaccurate. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FiCwqb5R7YmYCQvXVybHG4 --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent d407f0d commit fd21161

1 file changed

Lines changed: 171 additions & 0 deletions

File tree

‎descriptions/0/api.intercom.io.yaml‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6252,6 +6252,144 @@ paths:
62526252
summary: Company not found
62536253
value:
62546254
body: Hello
6255+
"/companies/search":
6256+
post:
6257+
summary: Search companies
6258+
parameters:
6259+
- name: Intercom-Version
6260+
in: header
6261+
schema:
6262+
"$ref": "#/components/schemas/intercom_version"
6263+
tags:
6264+
- Companies
6265+
operationId: searchCompanies
6266+
description: |
6267+
You can search for companies by the value of their attributes in order to fetch exactly the companies you want.
6268+
6269+
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.
6270+
6271+
Note that the API does not include companies who have no associated users in search results.
6272+
6273+
{% admonition type="warning" name="Optimizing search queries" %}
6274+
Search queries can be complex, so optimizing them can help the performance of your search.
6275+
Use the `AND` and `OR` operators to combine multiple filters to get the exact results you need and utilize
6276+
pagination to limit the number of results returned. The default is `15` results per page.
6277+
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.
6278+
{% /admonition %}
6279+
6280+
### Nesting & Limitations
6281+
6282+
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).
6283+
There are some limitations to the amount of multiple's there can be:
6284+
* There's a limit of max 2 nested filters
6285+
* There's a limit of max 15 filters for each AND or OR group
6286+
6287+
### Accepted Fields
6288+
6289+
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"`).
6290+
6291+
| Field | Type |
6292+
| ---------------------------------- | ------------------------------ |
6293+
| company_id | String |
6294+
| name | String |
6295+
| created_at | Date (UNIX Timestamp) |
6296+
| updated_at | Date (UNIX Timestamp) |
6297+
| remote_created_at | Date (UNIX Timestamp) |
6298+
| last_request_at | Date (UNIX Timestamp) |
6299+
| monthly_spend | Integer |
6300+
| session_count | Integer |
6301+
| user_count | Integer |
6302+
| tag_id | String |
6303+
| custom_attributes.{attribute_name} | String |
6304+
6305+
The `plan.id` and `plan.name` fields are not searchable and return a `400` error with code `invalid_field`.
6306+
6307+
### Accepted Operators
6308+
6309+
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. The `IN` and `NIN` operators are not supported for Date fields.
6310+
6311+
| Operator | Valid Types | Description |
6312+
| :------- | :------------------------------- | :--------------------------------------------------------------- |
6313+
| = | All | Equals |
6314+
| != | All | Doesn't Equal |
6315+
| IN | All except Date and tag_id | In<br>Shortcut for `OR` queries<br>Values must be in Array |
6316+
| NIN | All except Date and tag_id | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
6317+
| > | Integer<br>Date (UNIX Timestamp) | Greater than |
6318+
| < | Integer<br>Date (UNIX Timestamp) | Lower than |
6319+
| ~ | String | Contains |
6320+
| !~ | String | Doesn't Contain |
6321+
| ^ | String | Starts With |
6322+
| $ | String | Ends With |
6323+
6324+
### Sorting
6325+
6326+
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.
6327+
responses:
6328+
'200':
6329+
description: successful
6330+
content:
6331+
application/json:
6332+
examples:
6333+
successful:
6334+
value:
6335+
type: list
6336+
data: []
6337+
total_count: 0
6338+
pages:
6339+
type: pages
6340+
page: 1
6341+
per_page: 5
6342+
total_pages: 0
6343+
schema:
6344+
"$ref": "#/components/schemas/company_list"
6345+
'401':
6346+
description: Unauthorized
6347+
content:
6348+
application/json:
6349+
examples:
6350+
Unauthorized:
6351+
value:
6352+
type: error.list
6353+
request_id: f0dc95f1-9e46-4e8d-8150-89365c2c5195
6354+
errors:
6355+
- code: unauthorized
6356+
message: Access Token Invalid
6357+
schema:
6358+
"$ref": "#/components/schemas/error"
6359+
'400':
6360+
description: Bad Request
6361+
content:
6362+
application/json:
6363+
examples:
6364+
Unsupported field:
6365+
value:
6366+
type: error.list
6367+
request_id: 8d6c1f0a-3b2e-4a17-9c5d-1f0e2a3b4c5d
6368+
errors:
6369+
- code: invalid_field
6370+
message: "segment_id is not a valid search field"
6371+
schema:
6372+
"$ref": "#/components/schemas/error"
6373+
requestBody:
6374+
content:
6375+
application/json:
6376+
schema:
6377+
"$ref": "#/components/schemas/company_search_request"
6378+
examples:
6379+
successful:
6380+
summary: successful
6381+
value:
6382+
query:
6383+
operator: AND
6384+
value:
6385+
- field: name
6386+
operator: "="
6387+
value: my-company
6388+
sort:
6389+
field: name
6390+
order: ascending
6391+
pagination:
6392+
per_page: 5
62556393
"/companies/list":
62566394
post:
62576395
summary: List all companies
@@ -36539,6 +36677,39 @@ components:
3653936677
"$ref": "#/components/schemas/starting_after_paging"
3654036678
required:
3654136679
- query
36680+
company_search_request:
36681+
description: Search for companies using Intercom's Search API.
36682+
type: object
36683+
title: Company search request
36684+
properties:
36685+
query:
36686+
oneOf:
36687+
- "$ref": "#/components/schemas/single_filter_search_request"
36688+
title: Single filter search request
36689+
- "$ref": "#/components/schemas/multiple_filter_search_request"
36690+
title: multiple filter search request
36691+
pagination:
36692+
"$ref": "#/components/schemas/starting_after_paging"
36693+
sort:
36694+
type: object
36695+
description: An optional object to sort the results by.
36696+
properties:
36697+
field:
36698+
type: string
36699+
description: The field to sort the results on.
36700+
example: created_at
36701+
order:
36702+
type: string
36703+
description: The order to sort the results in. Defaults to `descending`
36704+
when omitted. Values other than `ascending` or `descending` return a
36705+
`400` error with code `invalid_sort_order`.
36706+
enum:
36707+
- ascending
36708+
- descending
36709+
default: descending
36710+
example: descending
36711+
required:
36712+
- query
3654236713
segment:
3654336714
title: Segment
3654436715
type: object

0 commit comments

Comments
 (0)