Company Search reference - Crustdata Docs

Reference material for Company Search: 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 and Examples.

Ranked search

Pass a search object to rank companies against a natural-language query. search.query is required and must not be empty. search.mode controls which retrieval methods run.

Mode	Keyword retrieval	Semantic retrieval	When to use
`hybrid`	Yes	Yes	Most discovery queries. This is the default.
`lexical`	Yes	No	Queries where matching the supplied words matters most.
`semantic`	No	Yes	Conceptual queries that may use different wording from descriptions.

When you supply filters, the API applies them as hard constraints before keyword or semantic retrieval. Ranked results are ordered by relevance, so you cannot combine search with sorts. Ranked search returns up to 100 results and does not support cursor pagination in the current version.

{
    "search": {
        "query": "developer tooling companies building observability products",
        "mode": "hybrid"
    },
    "filters": {
        "field": "locations.country",
        "type": "=",
        "value": "USA"
    },
    "limit": 20
}

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"]`
`is_null`	`null`	Field has no value	`null`	The `value` key is required — send `"value": null`.
`is_not_null`	`null`	Field has a non-null value	`null`	The `value` key is required — send `"value": null`.
`(.)`	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_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`

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 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.

{
    "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. 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.status`	string	Yes	No	Company lifecycle: `"active"` or `"deleted"`
`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

basic_info.status is the company’s lifecycle in Crustdata’s entity graph. It is the same value the person APIs return as company_status on an employment record. Two values are defined:

active: a live company record.
deleted: a record Crustdata has retired. Other records can still point at it, so you meet this value most often in a person’s employment history.

Company search serves the live company index, so a deleted company is not a result there. Filter basic_info.status when you want the check written into the query, and read it on the response to see the lifecycle of a company you already matched.

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.<function>`	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.

Replace <function> 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.

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."`)
`locations.all_office_addresses`	string[]	Yes	No	All office addresses, HQ and non-HQ; match a city or region substring with `(.)`

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 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 %

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 category slugs
`technographics.technologies.super_category`	string[]	Yes	No	Detected technology super-category slugs

Technographics values are not returned in search responses — these fields are filter-only. technographics.total_technologies is filterable and sortable, but it is not returned in results. technographics.top_technologies is filterable but likewise not returned. technographics.technologies.name is likewise not returned, and technographics.technologies.category and technographics.technologies.super_category are likewise not returned. To get the values, request the technographics field group on Company Enrich. Use Autocomplete with the technology and technology_category fields to discover valid filter values.

Use Autocomplete 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`, `status`	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.

Field family	Filterable	Returned
`competitors.*` (`company_ids`, `websites`)	Yes	No
`roles.*` (`distribution.<function>`, `distribution_percent`, `growth_6m`, `growth_yoy`)	Yes	No
`technographics.*` (`total_technologies`, `top_technologies`, `technologies.name`, `technologies.category`, `technologies.super_category`)	Yes	No

Validation rules

Default/max limits and pagination behavior reflect current platform behavior. See the API reference for the formal OpenAPI contract.

Rule	Behavior
Request criteria	Supply at least one of `filters` or `search`.
`search.query`	Required and non-empty when `search` is present.
`search.mode`	One of `hybrid`, `lexical`, or `semantic`. Defaults to `hybrid`.
`fields` is optional	Omitting returns all fields (large payload). Always specify in production.
Filter-only `limit`	1 to 1000. Default: 20.
Ranked-search `limit`	1 to 100. Default: 20.
Ranked search with `sorts`	Not supported. Ranked results preserve relevance order.
Ranked search with `cursor`	Not supported in the current version.
`sorts` with pagination	For filter-only search, include `sorts` when paginating to ensure stable result ordering.
`cursor` must match query	For filter-only search, changing `filters`, `sorts`, or `fields` between pages invalidates it.

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:

400 — Unsupported field

{
    "error": {
        "type": "invalid_request",
        "message": "Unsupported columns in conditions: ['nonexistent_field']",
        "metadata": []
    }
}

400 — Invalid operator

{
    "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.

401 — Invalid API key

{
    "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`, `search`, `fields`, `sorts`, `limit`, `cursor`
Response	`{ companies, next_cursor, total_count }`
Pagination	Cursor-based for filter-only search. Ranked search returns one relevance-ordered window.
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. sorts is not supported with ranked search. Ranked results are ordered by relevance.

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.

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.

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 for the complete OpenAPI schema.

​Ranked search

​Filter operator reference

​geo_distance — radius around headquarters

​geo_exclude — exclude a radius

​Searchable fields

​Identity & timestamps

​Basic info

​Revenue & funding

​Headcount & roles

​Locations

​Taxonomy

​Followers

​Social profiles

​Competitors (filter-only)

​Technographics (filter-only)

​Response fields

​Filterable but not returned

​Validation rules

​Errors

​API reference summary

​How sorts work

​Paginate through results

Ranked search

Filter operator reference

`geo_distance` — radius around headquarters

`geo_exclude` — exclude a radius

Searchable fields

Identity & timestamps

Basic info

Revenue & funding

Headcount & roles

Locations

Taxonomy

Followers

Social profiles

Competitors (filter-only)

Technographics (filter-only)

Response fields

Filterable but not returned

Validation rules

Errors

API reference summary

How sorts work

Paginate through results