Company search

POST /screener/companydb/search

POST /company/search

This page lists every behavioral and contract change between the legacy company-search endpoint and the current one. Use it as a side-by-side reference when porting an integration; each section gives the old shape, the new shape, and the smallest edit that closes the gap.

Topic	Legacy	Current
Path	`POST /screener/companydb/search`	`POST /company/search`
Auth	`Authorization: Bearer <key>`	`Authorization: Bearer <key>`
Version	(not required)	`x-api-version: 2025-11-01` (required)
Base URL	`https://api.crustdata.com`	`https://api.crustdata.com`

The x-api-version header is required on every request to /company/search. Calls without it are rejected. The legacy endpoint did not use this header.

1. Request body — top-level keys

Key	Legacy	Current	Notes
`filters`	object	object	Grammar changed — see Filter grammar below.
`sorts`	array of `{column, order}`	array of `{column, order}`	Unchanged.
`limit`	integer 1–1000, default 20	integer 1–1000, default 20	Unchanged.
`count`	integer alias for `limit`	integer alias for `limit`	Unchanged.
`cursor`	string nullable	string nullable	Unchanged.
`fields`	(not supported)	string[]	New — request a subset of response sections via dot-paths.
`preview`	boolean	boolean	Unchanged.
`search`	object (semantic / hybrid)	(removed)	Semantic/hybrid search has no replacement on this endpoint — see Removed features.
`return_query`	boolean (debug)	boolean (accepted, response does not include `query`)	Behavioral change.

2. Filter grammar

The condition key changed from column to field. Operator names and the and/or group shape are unchanged.

{
    "column": "linkedin_industries",
    "type": "in",
    "value": ["Software Development"]
}

Two changes per condition:

Rename column → field.
Map the legacy field name to the new dataset path (see Field-name mapping).

Operators

Operator	Legacy	Current	Notes
`=`	✅	✅
`!=`	✅	✅
`<`, `>`	✅	✅
`=<`, `=>`	✅	✅	`>=` and `<=` are not supported — use `=>` / `=<`.
`in`, `not_in`	✅	✅	Value must be an array.
`(.)`	✅	✅	Fuzzy / all-words match.
`[.]`	✅	✅	Exact phrase match.
`is_null`, `is_not_null`	✅	✅	Unchanged.

`and` / `or` groups

The group shape is unchanged — op: "and" or op: "or" plus a conditions array. Only the leaf-condition key (column → field) and the leaf field names need to change.

3. Field-name mapping

The legacy endpoint exposed flat names like company_name, hq_country, and employee_metrics.latest_count. The current endpoint groups those fields under basic_info, headcount, funding, taxonomy, revenue, and locations.

Identity and profile

Legacy field	Current field
`company_id`	`basic_info.company_id` (also exposed at top level as `crustdata_company_id`)
`company_name`	`basic_info.name`
`company_website_domain`	`basic_info.primary_domain`
`company_website`	`basic_info.website`
`domains`	`basic_info.all_domains`
`linkedin_profile_url`	`basic_info.professional_network_url`
`linkedin_profile_name`	`basic_info.profile_name`
`linkedin_id`	`basic_info.professional_network_id`
`linkedin_company_description`	`basic_info.description`
`company_type`	`basic_info.company_type`
`year_founded`	`basic_info.year_founded` (now an integer; see Type changes)
`employee_count_range`	`basic_info.employee_count_range`
`markets`	`basic_info.markets`
`linkedin_categories`	`basic_info.industries`

Taxonomy

Legacy field	Current field
`linkedin_industries`	`taxonomy.professional_network_industries` (array)
`linkedin_industry`	`taxonomy.professional_network_industry` (single label)
`linkedin_specialities`	`taxonomy.professional_network_specialities`
`crunchbase_categories`	`taxonomy.categories`

Headcount and roles

Legacy field	Current field
`employee_metrics.latest_count`	`headcount.total`
`largest_headcount_country`	`headcount.largest_headcount_country`
`role_distribution.*`	`roles.distribution.*`
`role_distribution_percent.*`	(removed — request `roles.distribution` and compute percentages client-side)
`role_growth_6m.*`	`roles.growth_6m.*`
`role_growth_yoy.*`	`roles.growth_yoy.*`
`employee_metrics.growth_*`	(removed; superseded by `roles.growth_*`)

Followers

Legacy field	Current field
`follower_metrics.latest_count`	`followers.count`
`follower_metrics.growth_1m_percent`	`followers.mom_percent`
`follower_metrics.growth_3m_percent`	`followers.qoq_percent`
`follower_metrics.growth_6m_percent`	`followers.six_months_growth_percent`
`follower_metrics.growth_12m_percent`	`followers.yoy_percent`

Revenue and public-market data

Legacy field	Current field
`estimated_revenue_lower_bound_usd`	`revenue.estimated.lower_bound_usd`
`estimated_revenue_higher_bound_usd`	`revenue.estimated.upper_bound_usd`
`acquisition_status`	`revenue.acquisition_status`
`stock_symbols`	`revenue.public_markets.stock_symbols`
`fiscal_year_end`	`revenue.public_markets.fiscal_year_end`
`ipo_date`	(removed from search; available via Company Enrich)

Funding and investors

Legacy field	Current field
`crunchbase_total_investment_usd`	`funding.total_investment_usd`
`last_funding_round_investment_usd`	`funding.last_round_amount_usd`
`last_funding_round_type`	`funding.last_round_type`
`last_funding_date`	`funding.last_fundraise_date`
`crunchbase_investors`	`funding.investors`
`tracxn_investors`	`funding.tracxn_investors`
`crunchbase_valuation_usd`	(removed from search; available via enrich as `funding.valuation_usd`)

Locations

Legacy field	Current field
`hq_country`	`locations.country`
`hq_location`	`locations.headquarters`
`hq_street_address_and_city`	`locations.headquarters`
`office_addresses`	`locations.all_office_addresses`

Competitors

Legacy field	Current field
`competitor_ids`	`competitors.company_ids`
`competitor_websites`	`competitors.websites`

Legacy field	Current field
`twitter_handle`	`social_profiles.twitter_url`
`twitter_profile_url`	`social_profiles.twitter_url`
`crunchbase_profile_url`	`social_profiles.crunchbase.url`
`crunchbase_uuid`	`social_profiles.crunchbase.uuid`

For the full searchable-field catalog, see Company Search reference.

4. Type changes

Field	Legacy type	Current type	Notes
`year_founded`	string	integer	Past responses returned `"2017"`; current responses return `2017`.
`last_funding_date` / `funding.last_fundraise_date`	string	string (ISO 8601 `YYYY-MM-DD`)	Format clarified.

year_founded is now an integer. Update any parsing logic that expected a quoted string ("2017") — values are now bare numbers (2017).

5. Removed features

Semantic search (`search` parameter)

The legacy endpoint accepted a top-level search object for natural-language queries:

{
    "search": {
        "query": "fintech companies hiring engineers",
        "mode": "hybrid"
    }
}

The current endpoint does not accept search. Sending it returns 400. Use structured filters instead, or contact support@crustdata.co if you need semantic retrieval for an account.

`single_query` debug flag

Removed. The flag had no externally documented behavior.

`crunchbase_valuation_usd` / `crunchbase_valuation_date` filters

Not supported as search filters. The valuation is still returned by Company Enrich.

`ipo_date` filter

Removed from search filters. The value is still returned by Company Enrich.

Flat per-section growth fields

employee_metrics.growth_* and follower_metrics.growth_* are no longer filterable as flat fields. Use roles.growth_* for headcount growth and followers.{mom_percent, qoq_percent, six_months_growth_percent, yoy_percent} for follower growth.

`role_distribution_percent.*`

Removed. Request roles.distribution (raw counts) and compute percentages in your client.

6. Added features

Feature	Description
`fields` parameter	Request only the dot-paths you need (e.g. `["basic_info.name", "headcount.total"]`).
Nested response sections	Records return structured `basic_info`, `headcount`, `funding`, `taxonomy`, `revenue`, `locations`, `competitors`, `followers`, `social_profiles`, `hiring`, `roles` sections.
Stable error envelope	All `4xx`/`5xx` errors return `{ "error": { "type", "message", "metadata" } }` (legacy returned `{ "error": "...", "details": {...} }`).
`updated_at` and `indexed_at`	New top-level timestamps marking the most recent profile refresh and indexing.
Live `professional_network` profile	`social_profiles.professional_network` returns the company’s professional-network profile URL alongside legacy social links.
Discoverable filter values	Company Autocomplete returns valid indexed values for any supported field.

7. Response shape

The response envelope keeps the same top-level keys, but each company object moved from a flat structure to a nested one.

Envelope

Key	Legacy	Current
`companies`	array of companies	array of companies
`next_cursor`	string \| null	string \| null
`total_count`	integer \| null	integer \| null
`query`	present when `return_query: true`	(not returned)

Company object

Legacy records returned a flat object with keys like company_name, linkedin_profile_url, hq_country, linkedin_followers, and per-section nested objects (employee_metrics, follower_metrics, funding_and_investment, etc.). Current records group those fields into named sections:

{
    "company_id": 633593,
    "company_name": "Retool",
    "company_website_domain": "retool.com",
    "year_founded": "2017",
    "hq_country": "USA",
    "employee_metrics": { "latest_count": 443 },
    "follower_metrics": { "latest_count": 95000 },
    "estimated_revenue_lower_bound_usd": 50000000
}

Response-key map

Legacy key	Current key
`company_id`	`crustdata_company_id` (top-level) / `basic_info.company_id`
`company_name`	`basic_info.name`
`company_website_domain` / `domains`	`basic_info.primary_domain` / `basic_info.all_domains`
`linkedin_profile_url`	`basic_info.professional_network_url`
`linkedin_industries`	`taxonomy.professional_network_industries`
`year_founded`	`basic_info.year_founded`
`hq_country` / `hq_location`	`locations.country` / `locations.headquarters`
`employee_metrics.latest_count`	`headcount.total`
`follower_metrics.latest_count`	`followers.count`
`estimated_revenue_lower_bound_usd`	`revenue.estimated.lower_bound_usd`
`estimated_revenue_higher_bound_usd`	`revenue.estimated.upper_bound_usd`
`crunchbase_total_investment_usd`	`funding.total_investment_usd`
`last_funding_round_type`	`funding.last_round_type`
`last_funding_date`	`funding.last_fundraise_date`
`competitor_ids` / `competitor_websites`	`competitors.company_ids` / `competitors.websites`

Use the fields request parameter to request just the sections you need (for example, fields: ["basic_info.name", "headcount.total"]). This keeps responses small and avoids parsing sections you do not use. See Response fields.

8. Error responses

The error envelope changed shape. Status codes are unchanged (400, 401, 403, 500).

{
    "error": "Unsupported column 'industry'",
    "details": { "supported_columns": ["company_name", "linkedin_industries", "..."] }
}

401 continues to use a flat { "message": "Invalid API key in request" } shape — parse based on HTTP status.

9. End-to-end example

The same query — software-development companies headquartered in the USA, sorted by headcount — written against both endpoints.

curl --request POST \
  --url https://api.crustdata.com/screener/companydb/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        { "column": "linkedin_industries", "type": "in", "value": ["Software Development"] },
        { "column": "hq_country",          "type": "=",  "value": "USA" }
      ]
    },
    "sorts": [{"column": "employee_metrics.latest_count", "order": "desc"}],
    "limit": 2
  }'

1. Request body — top-level keys

2. Filter grammar

Operators

`and` / `or` groups

3. Field-name mapping

Identity and profile

Taxonomy

Headcount and roles

Followers

Revenue and public-market data

Funding and investors

Locations

Competitors

4. Type changes

5. Removed features

Semantic search (`search` parameter)

`single_query` debug flag

`crunchbase_valuation_usd` / `crunchbase_valuation_date` filters

`ipo_date` filter

Flat per-section growth fields

`role_distribution_percent.*`

6. Added features

7. Response shape

Envelope

Company object

Response-key map

8. Error responses

9. End-to-end example

Migration checklist

See also

Documentation Index

​1. Request body — top-level keys

​2. Filter grammar

​Operators

​and / or groups

​3. Field-name mapping

​Identity and profile

​Taxonomy

​Headcount and roles

​Followers

​Revenue and public-market data

​Funding and investors

​Locations

​Competitors

​Social profiles

​4. Type changes

​5. Removed features

​Semantic search (search parameter)

​single_query debug flag

​crunchbase_valuation_usd / crunchbase_valuation_date filters

​ipo_date filter

​Flat per-section growth fields

​role_distribution_percent.*

​6. Added features

​7. Response shape

​Envelope

​Company object

​Response-key map

​8. Error responses

​9. End-to-end example

​Migration checklist

​See also

1. Request body — top-level keys

2. Filter grammar

Operators

`and` / `or` groups

3. Field-name mapping

Identity and profile

Taxonomy

Headcount and roles

Followers

Revenue and public-market data

Funding and investors

Locations

Competitors

Social profiles

4. Type changes

5. Removed features

Semantic search (`search` parameter)

`single_query` debug flag

`crunchbase_valuation_usd` / `crunchbase_valuation_date` filters

`ipo_date` filter

Flat per-section growth fields

`role_distribution_percent.*`

6. Added features

7. Response shape

Envelope

Company object

Response-key map

8. Error responses

9. End-to-end example

Migration checklist

See also