> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Company Search reference
> Reference for Company Search: filter operators, searchable fields, response fields, validation rules, and errors.
Reference material for [Company Search](/company-docs/search/introduction): the full list
of filter operators, searchable fields with sortable flags, response fields,
validation rules, and error responses.
For walk-through examples, see [Company Search](/company-docs/search/introduction) and
[Examples](/company-docs/search/examples).
***
## Filter operator reference
Company Search accepts the following `filters.type` operators.
| Operator | Value shape | Meaning | Example value | Notes |
| -------------- | ------------------------------ | ---------------------------- | ------------------------ | ---------------------------------------------------------------------------- |
| `=` | scalar | Exact match | `"retool.com"` | Case-insensitive for text fields |
| `!=` | scalar | Not equal | `"acquired"` | |
| `<` | scalar (number or date string) | Less than | `10000` | Numbers and date strings |
| `=<` | scalar (number or date string) | Less than or equal | `50000000` | **Not** `<=` |
| `>` | scalar (number or date string) | Greater than | `2020` | Numbers and date strings |
| `=>` | scalar (number or date string) | Greater than or equal | `"2024-01-01"` | **Not** `>=` |
| `in` | array | Value is in list | `["USA", "GBR"]` | Case-sensitive. Matches if **any** array element matches **any** list value. |
| `not_in` | array | Value is not in list | `["acquired"]` | |
| `contains` | scalar | Field contains value | `"cloud"` | Use for substring-style matching on supported text fields |
| `not_contains` | scalar | Field does not contain value | `"agency"` | Use to exclude substring-style matches on supported text fields |
| `is_null` | none | Field is null | — | No `value` needed |
| `is_not_null` | none | Field is not null | — | No `value` needed |
| `(.)` | string | Fuzzy text search | `"openai"` | Tolerates typos, matches word variants |
| `[.]` | string | Exact token match | `"Software Development"` | No typos allowed, requires exact tokens |
The operators `>=` and `<=` are **not supported**. Use `=>` and `=<`
instead.
## Searchable fields
These are common fields that can be used in the `field` key of a filter condition. Some indexed filter fields are search-only and are not returned in the response payload. For the full schema, see the [API reference](/openapi-specs/2025-11-01/introduction).
Fields are grouped by family below. Every field listed is filterable; the **Sortable** column marks the subset also valid in `sorts`.
### Identity & timestamps
| Field | Type | Sortable | Description |
| ---------------------------------- | -------- | -------- | ------------------------------ |
| `crustdata_company_id` | integer | Yes | Crustdata company ID |
| `basic_info.company_id` | integer | Yes | Internal source company ID |
| `metadata.growth_calculation_date` | datetime | Yes | Anchor date for growth metrics |
| `updated_at` | datetime | Yes | Last profile update timestamp |
| `indexed_at` | datetime | Yes | Last index timestamp |
### Basic info
| Field | Type | Sortable | Description |
| ------------------------------------- | --------- | -------- | -------------------------------------------- |
| `basic_info.name` | string | Yes | Company name |
| `basic_info.primary_domain` | string | Yes | Primary website domain |
| `basic_info.website` | string | No | Full website URL |
| `basic_info.professional_network_url` | string | No | Company profile URL |
| `basic_info.professional_network_id` | string | No | Company profile ID |
| `basic_info.company_type` | string | No | e.g., `"Privately Held"`, `"Public Company"` |
| `basic_info.year_founded` | integer | Yes | Year founded (e.g., `2017`) |
| `basic_info.employee_count_range` | string | Yes | e.g., `"201-500"` |
| `basic_info.markets` | string\[] | No | Market tags |
| `basic_info.industries` | string\[] | No | Industry tags |
### Revenue & funding
| Field | Type | Sortable | Description |
| ---------------------------------------- | --------- | -------- | ------------------------------------ |
| `revenue.estimated.lower_bound_usd` | integer | Yes | Revenue lower bound (USD) |
| `revenue.estimated.upper_bound_usd` | integer | Yes | Revenue upper bound (USD) |
| `revenue.acquisition_status` | string | No | e.g., `"acquired"` |
| `revenue.public_markets.ipo_date` | date | Yes | IPO date (public companies) |
| `revenue.public_markets.fiscal_year_end` | string | No | Fiscal year end (public companies) |
| `revenue.public_markets.stock_symbols` | string\[] | No | Ticker symbols (public companies) |
| `funding.total_investment_usd` | number | Yes | Total disclosed funding (USD) |
| `funding.last_round_amount_usd` | number | Yes | Last funding round amount (USD) |
| `funding.last_fundraise_date` | date | Yes | Last funding date |
| `funding.last_round_type` | string | No | e.g., `"series_a"`, `"series_b"` |
| `funding.investors` | string\[] | No | Investor names |
| `funding.tracxn_investors` | string\[] | No | Indexed investor names (filter only) |
### Headcount & roles
| Field | Type | Sortable | Description |
| ------------------------------------- | ------- | -------- | --------------------------------------------- |
| `headcount.total` | integer | Yes | Total employee count |
| `headcount.largest_headcount_country` | string | Yes | Country with the most employees |
| `headcount.growth_percent.1m` | number | No | 1-month headcount growth percent |
| `headcount.growth_percent.3m` | number | No | 3-month headcount growth percent |
| `headcount.growth_percent.6m` | number | No | 6-month headcount growth percent |
| `headcount.growth_percent.12m` | number | No | 12-month headcount growth percent |
| `headcount.growth_absolute.1m` | integer | No | 1-month absolute employee delta |
| `headcount.growth_absolute.3m` | integer | No | 3-month absolute employee delta |
| `headcount.growth_absolute.6m` | integer | No | 6-month absolute employee delta |
| `headcount.growth_absolute.12m` | integer | No | 12-month absolute employee delta |
| `roles.distribution.` | integer | No | Employee count in a function (see list below) |
| `roles.distribution_percent` | object | No | Share of employees per function |
| `roles.growth_6m` | object | No | 6-month role growth |
| `roles.growth_yoy` | object | No | Year-over-year role growth |
The `headcount.growth_percent.*` and `headcount.growth_absolute.*` dotted
period paths are **filterable but not sortable**. To rank results by growth,
filter on the period you care about and sort on `headcount.total` (or
another sortable field). See [Find high-growth mid-size
companies](/company-docs/search/examples#find-high-growth-mid-size-companies).
Replace `` with one of: `accounting`, `administrative`, `arts_and_design`, `business_development`, `community_and_social_services`, `consulting`, `customer_success_and_support`, `education`, `engineering`, `entrepreneurship`, `finance`, `healthcare_services`, `human_resources`, `information_technology`, `legal`, `marketing`, `media_and_communication`, `military_and_protective_services`, `operations`, `product_management`, `program_and_project_management`, `purchasing`, `quality_assurance`, `real_estate`, `research`, `sales`, `support`. For example, `roles.distribution.engineering` filters on the number of engineers. See [Find companies by team size in a function](/company-docs/search/examples#find-companies-by-team-size-in-a-function).
### Locations
| Field | Type | Sortable | Description |
| -------------------------- | ------ | -------- | --------------------------------------------- |
| `locations.country` | string | Yes | HQ country (ISO-3: `"USA"`, `"GBR"`) |
| `locations.headquarters` | string | No | Full HQ location string |
| `locations.street_address` | string | No | HQ street address (e.g. `"510 Townsend St."`) |
### Taxonomy
| Field | Type | Sortable | Description |
| -------------------------------------------- | --------- | -------- | ---------------------- |
| `taxonomy.professional_network_industry` | string | No | Primary industry label |
| `taxonomy.categories` | string\[] | No | Category tags |
| `taxonomy.professional_network_specialities` | string\[] | No | Speciality tags |
### Followers
| Field | Type | Sortable | Description |
| ------------------------------------- | ------- | -------- | ---------------------------------- |
| `followers.count` | integer | Yes | Follower count |
| `followers.mom_percent` | number | No | Month-over-month follower growth % |
| `followers.qoq_percent` | number | No | Quarter-over-quarter growth % |
| `followers.six_months_growth_percent` | number | No | 6-month follower growth % |
| `followers.yoy_percent` | number | No | Year-over-year follower growth % |
### Social profiles
| Field | Type | Sortable | Description |
| -------------------------------------- | ------ | -------- | ----------------------- |
| `social_profiles.twitter_url` | string | No | Company X/Twitter URL |
| `social_profiles.crunchbase.url` | string | No | Company Crunchbase URL |
| `social_profiles.crunchbase.uuid` | string | No | Company Crunchbase UUID |
| `social_profiles.professional_network` | string | No | Company profile URL |
### Competitors (filter-only)
| Field | Type | Sortable | Description |
| ------------------------- | ---------- | -------- | ------------------------ |
| `competitors.company_ids` | integer\[] | No | Competitor Crustdata IDs |
| `competitors.websites` | string\[] | No | Competitor domains |
Use [Autocomplete](/company-docs/autocomplete/introduction) to discover
exact values for fields like `basic_info.industries`,
`taxonomy.professional_network_industry`, `locations.country`,
`basic_info.company_type`, and `funding.last_round_type`.
## Response fields
Each company in the response can include these sections (depending on `fields`):
| Section | Key fields | Description |
| ----------------- | ---------------------------------------------------------------------------------- | --------------------------------- |
| `basic_info` | `name`, `primary_domain`, `website`, `professional_network_url`, `year_founded` | Core identity and profile |
| `headcount` | `total` | Employee footprint |
| `funding` | `total_investment_usd`, `last_round_amount_usd`, `investors` | Funding and investor data |
| `locations` | `country`, `state`, `headquarters`, `street_address`, `all_office_addresses` | Headquarters and office locations |
| `taxonomy` | `professional_network_industry`, `categories`, `professional_network_specialities` | Industry and category tags |
| `revenue` | `estimated`, `public_markets`, `acquisition_status` | Revenue and market data |
| `hiring` | `openings_count`, `openings_growth_percent` | Hiring demand |
| `followers` | `count`, `mom_percent`, `yoy_percent` | Social follower metrics |
| `social_profiles` | `twitter_url`, `professional_network`, `crunchbase.url`, `crunchbase.uuid` | Third-party profile links |
***
## Validation rules
Default/max limits and pagination behavior reflect current platform
behavior. See the [API reference](/openapi-specs/2025-11-01/introduction)
for the formal OpenAPI contract.
| Rule | Behavior |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| `filters` is optional | Omitting filters matches all companies. Always use filters in production to control cost. |
| `fields` is optional | Omitting returns all fields (large payload). Always specify in production. |
| `limit` range | 1–1000. Default: 20. |
| `sorts` with pagination | Always include `sorts` when paginating to ensure stable result ordering. |
| `cursor` must match query | Changing `filters`, `sorts`, or `fields` between pages invalidates the cursor. |
## Errors
Common error responses for Search:
```json 400 — Unsupported field theme={"theme":"vitesse-black"}
{
"error": {
"type": "invalid_request",
"message": "Unsupported columns in conditions: ['nonexistent_field']",
"metadata": []
}
}
```
```json 400 — Invalid operator theme={"theme":"vitesse-black"}
{
"error": {
"type": "invalid_request",
"message": "'filters.type' must be one of: =, !=, <, =<, >, =>, in, not_in, contains, not_contains, is_null, is_not_null, (.), [.]. Got '>='.",
"metadata": [
{
"field": "filters.type",
"type": "enum",
"message": "'filters.type' must be one of: =, !=, <, =<, >, =>, in, not_in, contains, not_contains, is_null, is_not_null, (.), [.]. Got '>='."
}
]
}
}
```
Use `=>` for greater-than-or-equal and `=<` for less-than-or-equal. The operators `>=` and `<=` are not supported.
```json 401 — Invalid API key theme={"theme":"vitesse-black"}
{
"error": {
"type": "unauthorized",
"message": "Invalid API key in request.",
"metadata": []
}
}
```
***
## API reference summary
| Detail | Value |
| ---------------- | ---------------------------------------------------------------------------------------------- |
| **Endpoint** | `POST /company/search` |
| **Auth** | Bearer token + `x-api-version: 2025-11-01` |
| **Request** | `filters` (condition or group), `fields`, `sorts`, `limit`, `cursor` |
| **Response** | `{ companies, next_cursor, total_count }` |
| **Pagination** | Cursor-based. Pass `next_cursor` in `cursor`. `null` = last page. |
| **Empty result** | `200` with `"companies": []` |
| **Errors** | `400` (bad field/operator), `401` (bad auth), `403` (permission/credits), `500` (server error) |
## How sorts work
The `sorts` parameter orders your results. Each sort rule needs:
* **`column`** — a dot-path field (e.g., `funding.total_investment_usd`, `headcount.total`, `basic_info.name`).
* **`order`** — either `asc` (ascending) or `desc` (descending).
You can provide multiple sort rules. The API applies them in order. For the
full list of sortable fields, see
[Search reference](/company-docs/search/reference#searchable-fields).
***
## Paginate through results
When your search matches more companies than your `limit`, use cursor-based pagination to walk through all pages.
**First page:** send your normal search request.
```bash First page theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/company/search \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"filters": {
"field": "locations.country",
"type": "in",
"value": ["USA"]
},
"sorts": [{"field": "crustdata_company_id", "order": "asc"}],
"limit": 100,
"fields": [
"crustdata_company_id",
"basic_info.name",
"basic_info.primary_domain"
]
}'
```
**Next page:** take the `next_cursor` value from the response and pass it in your next request. Keep the same `filters`, `sorts`, `limit`, and `fields`.
```bash Next page theme={"theme":"vitesse-black"}
curl --request POST \
--url https://api.crustdata.com/company/search \
--header 'authorization: Bearer YOUR_API_KEY' \
--header 'content-type: application/json' \
--header 'x-api-version: 2025-11-01' \
--data '{
"filters": {
"field": "locations.country",
"type": "in",
"value": ["USA"]
},
"sorts": [{"field": "crustdata_company_id", "order": "asc"}],
"limit": 100,
"fields": [
"crustdata_company_id",
"basic_info.name",
"basic_info.primary_domain"
],
"cursor": "PASTE_NEXT_CURSOR_VALUE_HERE"
}'
```
Continue until `next_cursor` is `null`, which means you have reached the last page.
Changing `filters`, `sorts`, or `fields` between pages invalidates the
cursor. Always include `sorts` when paginating to guarantee stable ordering.
See the [full API reference](/openapi-specs/2025-11-01/introduction) for the complete OpenAPI schema.