Skip to content

Add POST /companies/search (Preview) #599

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cox512 wants to merge 1 commit into
base: main
Choose a base branch
from
+129 −0
Open

Add POST /companies/search (Preview) #599

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 129 additions & 0 deletions descriptions/0/api.intercom.io.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<br>Shortcut for `OR` queries<br>Values must be in Array |
| NIN | All | Not In<br>Shortcut for `OR !` queries<br>Values must be in Array |
| > | Integer<br>Date (UNIX Timestamp) | Greater than |
| < | Integer<br>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
Expand Down