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.

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

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

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

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

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.

​Filter operator reference

​Searchable fields

​Identity & timestamps

​Basic info

​Revenue & funding

​Headcount & roles

​Locations

​Taxonomy

​Followers

​Social profiles

​Competitors (filter-only)

​Response fields

​Validation rules

​Errors

​API reference summary

​How sorts work

​Paginate through results

Filter operator reference

Searchable fields

Identity & timestamps

Basic info

Revenue & funding

Headcount & roles

Locations

Taxonomy

Followers

Social profiles

Competitors (filter-only)

Response fields

Validation rules

Errors

API reference summary

How sorts work

Paginate through results