> ## 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/introduction#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"]` | |
| `(.)` | string | Fuzzy text search | `"openai"` | Tolerates typos, matches word variants |
| `[.]` | string | Case-insensitive exact-phrase match | `"Software Development"` | Words must be contiguous and in order; no partial words or typos |
| `geo_distance` | object | HQ within radius of a location or explicit coordinate | `{"location": "Palo Alto, CA", "distance": 50, "unit": "km"}` | Only on `locations.headquarters`. See [`geo_distance`](#geo_distance--radius-around-headquarters) |
| `geo_exclude` | object | HQ outside radius of a location or explicit coordinate | `{"location": "London, UK", "distance": 100, "unit": "km"}` | Inverse of `geo_distance` — same value object and field. See [`geo_exclude`](#geo_exclude--exclude-a-radius) |
The operators `>=` and `<=` are **not supported**. Use `=>` and `=<`
instead.
### `geo_distance` — radius around headquarters
`geo_distance` keeps companies whose **headquarters** is within a radius of a
point. Both geo operators work on the `locations.headquarters` field only.
Supply the centre of the radius using **one** of:
* `location` — a string that is geocoded server-side (e.g. `"Palo Alto, CA"`).
* `lat_lng` — explicit coordinates as `[lat, lng]`. Skips geocoding.
If both are supplied, `lat_lng` wins. `distance` is required; `unit` defaults
to `km`.
| Field | Type | Required | Notes |
| ---------- | --------- | -------- | -------------------------------------------------------------------------- |
| `location` | string | One of | Geocoded server-side. Ignored when `lat_lng` is also set. |
| `lat_lng` | number\[] | One of | Two-element `[lat, lng]`. Lat in `[-90, 90]`, lng in `[-180, 180]`. |
| `distance` | number | Yes | Radius around the centre. Must be positive. |
| `unit` | string | No | One of `km`, `mi`, `miles`, `m`, `meters`, `ft`, `feet`. Defaults to `km`. |
See [`geo_distance` examples](/company-docs/search/introduction#examples)
for end-to-end requests using both `location` and `lat_lng`.
### `geo_exclude` — exclude a radius
`geo_exclude` is the inverse of `geo_distance`: it removes companies
headquartered **inside** the radius and keeps everyone else. It takes the same
value object — `location` or `lat_lng`, a required `distance`, and an optional
`unit` (defaults to `km`) — and works on the same `locations.headquarters`
field. Use it to carve out a metro you already cover, or to target companies
outside a region.
```json theme={"theme":"vitesse-black"}
{
"field": "locations.headquarters",
"type": "geo_exclude",
"value": { "location": "London, UK", "distance": 100, "unit": "km" }
}
```
## 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 | Filterable | Sortable | Description |
| ---------------------------------- | -------- | ---------- | -------- | ------------------------------ |
| `crustdata_company_id` | integer | Yes | Yes | Crustdata company ID |
| `basic_info.company_id` | integer | Yes | Yes | Internal source company ID |
| `metadata.growth_calculation_date` | datetime | Yes | Yes | Anchor date for growth metrics |
| `updated_at` | datetime | Yes | Yes | Last profile update timestamp |
| `indexed_at` | datetime | Yes | Yes | Last index timestamp |
### Basic info
| Field | Type | Filterable | Sortable | Description |
| ------------------------------------- | --------- | ---------- | -------- | -------------------------------------------- |
| `basic_info.name` | string | Yes | Yes | Company name |
| `basic_info.primary_domain` | string | Yes | Yes | Primary website domain |
| `basic_info.website` | string | Yes | No | Full website URL |
| `basic_info.professional_network_url` | string | Yes | No | Company profile URL |
| `basic_info.professional_network_id` | string | Yes | No | Company profile ID |
| `basic_info.company_type` | string | Yes | No | e.g., `"Privately Held"`, `"Public Company"` |
| `basic_info.year_founded` | integer | Yes | Yes | Year founded (e.g., `2017`) |
| `basic_info.employee_count_range` | string | Yes | Yes | e.g., `"201-500"` |
| `basic_info.markets` | string\[] | Yes | No | Market tags |
| `basic_info.industries` | string\[] | Yes | No | Industry tags |
### Revenue & funding
| Field | Type | Filterable | Sortable | Description |
| ---------------------------------------- | --------- | ---------- | -------- | ------------------------------------------- |
| `revenue.estimated.lower_bound_usd` | integer | Yes | Yes | Revenue lower bound (USD) |
| `revenue.estimated.upper_bound_usd` | integer | Yes | Yes | Revenue upper bound (USD) |
| `revenue.acquisition_status` | string | Yes | No | e.g., `"acquired"` |
| `revenue.public_markets.ipo_date` | date | Yes | Yes | IPO date (public companies) |
| `revenue.public_markets.fiscal_year_end` | string | Yes | No | Fiscal year end (public companies) |
| `revenue.public_markets.stock_symbols` | string\[] | Yes | No | Ticker symbols (public companies) |
| `funding.total_investment_usd` | number | Yes | Yes | Total disclosed funding (USD) |
| `funding.last_round_amount_usd` | number | Yes | Yes | Last funding round amount (USD) |
| `funding.last_fundraise_date` | date | Yes | Yes | Last funding date |
| `funding.last_round_type` | string | Yes | No | Latest round type, e.g., `"series_a"` |
| `funding.investors` | string\[] | Yes | No | All-time investor names; not round-specific |
### Headcount & roles
| Field | Type | Filterable | Sortable | Description |
| ------------------------------------- | ------- | ---------- | -------- | --------------------------------------------- |
| `headcount.total` | integer | Yes | Yes | Total employee count |
| `headcount.largest_headcount_country` | string | Yes | Yes | Country with the most employees |
| `headcount.growth_percent.1m` | number | Yes | No | 1-month headcount growth percent |
| `headcount.growth_percent.3m` | number | Yes | No | 3-month headcount growth percent |
| `headcount.growth_percent.6m` | number | Yes | No | 6-month headcount growth percent |
| `headcount.growth_percent.12m` | number | Yes | No | 12-month headcount growth percent |
| `headcount.growth_absolute.1m` | integer | Yes | No | 1-month absolute employee delta |
| `headcount.growth_absolute.3m` | integer | Yes | No | 3-month absolute employee delta |
| `headcount.growth_absolute.6m` | integer | Yes | No | 6-month absolute employee delta |
| `headcount.growth_absolute.12m` | integer | Yes | No | 12-month absolute employee delta |
| `roles.distribution.` | integer | Yes | No | Employee count in a function (see list below) |
| `roles.distribution_percent` | object | Yes | No | Share of employees per function |
| `roles.growth_6m` | object | Yes | No | 6-month role growth |
| `roles.growth_yoy` | object | Yes | 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/introduction#examples).
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/introduction#examples).
### Locations
| Field | Type | Filterable | Sortable | Description |
| -------------------------- | ------ | ---------- | -------- | ------------------------------------------------------------------------------------ |
| `locations.country` | string | Yes | Yes | HQ country — filter with ISO-3 codes or full names; returns the normalized full name |
| `locations.state` | string | Yes | No | HQ state / region, normalized (e.g. `"California"`) |
| `locations.city` | string | Yes | No | HQ city, normalized (e.g. `"Palo Alto"`) |
| `locations.headquarters` | string | Yes | No | Full HQ location string — also the target of `geo_distance` / `geo_exclude` |
| `locations.street_address` | string | Yes | No | HQ street address (e.g. `"510 Townsend St."`) |
**Normalized location facets.** `locations.state` and `locations.city`
filter against and return normalized values derived from geocoding each
company's headquarters address — the value you see in a response is the
value you filter with. `locations.country` **accepts both** vocabularies:
ISO-3 codes (`"USA"`, `"GBR"`) and full country names (`"United States"`)
each match all companies, so existing ISO-3 filters keep working unchanged.
Responses return the normalized full country name. Use
[Autocomplete](/company-docs/autocomplete/introduction) to discover indexed
values before filtering.
### Taxonomy
| Field | Type | Filterable | Sortable | Description |
| -------------------------------------------- | --------- | ---------- | -------- | ---------------------- |
| `taxonomy.professional_network_industry` | string | Yes | No | Primary industry label |
| `taxonomy.categories` | string\[] | Yes | No | Category tags |
| `taxonomy.professional_network_specialities` | string\[] | Yes | No | Speciality tags |
### Followers
| Field | Type | Filterable | Sortable | Description |
| ------------------------------------- | ------- | ---------- | -------- | ---------------------------------- |
| `followers.count` | integer | Yes | Yes | Follower count |
| `followers.mom_percent` | number | Yes | No | Month-over-month follower growth % |
| `followers.qoq_percent` | number | Yes | No | Quarter-over-quarter growth % |
| `followers.six_months_growth_percent` | number | Yes | No | 6-month follower growth % |
| `followers.yoy_percent` | number | Yes | No | Year-over-year follower growth % |
### Social profiles
| Field | Type | Filterable | Sortable | Description |
| -------------------------------------- | ------ | ---------- | -------- | ----------------------- |
| `social_profiles.twitter_url` | string | Yes | No | Company X/Twitter URL |
| `social_profiles.crunchbase.url` | string | Yes | No | Company Crunchbase URL |
| `social_profiles.crunchbase.uuid` | string | Yes | No | Company Crunchbase UUID |
| `social_profiles.professional_network` | string | Yes | No | Company profile URL |
### Competitors (filter-only)
| Field | Type | Filterable | Sortable | Description |
| ------------------------- | ---------- | ---------- | -------- | ------------------------ |
| `competitors.company_ids` | integer\[] | Yes | No | Competitor Crustdata IDs |
| `competitors.websites` | string\[] | Yes | No | Competitor domains |
### Technographics (filter-only)
| Field | Type | Filterable | Sortable | Description |
| -------------------------------------- | --------- | ---------- | -------- | ------------------------------- |
| `technographics.total_technologies` | integer | Yes | Yes | Number of detected technologies |
| `technographics.top_technologies` | string\[] | Yes | No | Most notable technology names |
| `technographics.technologies.name` | string\[] | Yes | No | Detected technology names |
| `technographics.technologies.category` | string\[] | Yes | No | Detected technology categories |
Technographics values are **not returned** in search responses — these
fields are filter-only (`technographics.total_technologies` is also
sortable). To get the values, request the `technographics` field group on
[Company Enrich](/company-docs/enrichment/reference#technographics-fields).
Use [Autocomplete](/company-docs/autocomplete/introduction#common-fields-to-autocomplete)
with the `technology` and `technology_category` fields to discover valid
filter values.
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`, `city`, `headquarters`, `street_address`, `all_office_addresses` | Headquarters and office locations — `country`, `state`, and `city` are normalized geocoded values |
| `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 |
| `software_reviews` | `average_rating`, `review_count`, and review-count growth percentages | Software review metrics (when available) |
### Filterable but not returned
Some indexed fields can be used in `filters` to narrow results but are **not**
part of the response payload — search is lightweight discovery, not full
enrichment. Filter on them, then fetch their values with
[Company Enrich](/company-docs/enrichment/introduction).
| Field family | Filterable | Returned |
| ----------------------------------------------------------------------------------------------------------- | ---------- | -------- |
| `competitors.*` (`company_ids`, `websites`) | Yes | No |
| `roles.*` (`distribution.`, `distribution_percent`, `growth_6m`, `growth_yoy`) | Yes | No |
| `technographics.*` (`total_technologies`, `top_technologies`, `technologies.name`, `technologies.category`) | Yes | No |
***
## 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. |
**Filter sizing.** To match many values of a field, put them all in a single
`in` condition rather than many separate conditions — `in` compiles to one
efficient query. A single `in` list of up to \~5,000–10,000 values returns in a
few seconds; larger lists get progressively slower, and very large lists
(roughly 50,000+) are rejected. For bigger sets, split the values into
\~5,000–10,000 chunks across multiple requests and merge. The request body is
hard-capped at **10 MB** (larger bodies return `413 request_too_large`),
though with typical payloads you reach the query-size limit first.
## 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.