Batch Search Companies - Crustdata Docs

Authorizations

Authorization

string

header

required

API key passed as a Bearer token in the Authorization header.

Headers

x-api-version

enum<string>

default:2025-11-01

required

API version to use. Batch job submission requires 2025-11-01; requests without this header are rejected with 400.

Available options:

2025-11-01

Example:

"2025-11-01"

Body

application/json

One search query (filters plus optional sorts), result-volume controls, and optional field selection.

Request body for a batch company database search job. Provide one filters group; the job walks the paginated result set server-side until max_results is reached or the results are exhausted. The non-batch paging parameters (limit, page, preview) are ignored.

filters

object

required

Boolean group of database search conditions. Unlike the non-batch search endpoints, batch search requires the top level of filters to be a group — sending a bare condition returns 400. Groups can be nested inside conditions for complex queries.

Show child attributes

Example:

{
  "op": "and",
  "conditions": [
    {
      "field": "experience.employment_details.current.title",
      "type": "(.)",
      "value": "engineer"
    }
  ]
}

sorts

object[]

Optional sort directives applied to matched companies in order, identical to the non-batch /company/search sorts parameter.

Show child attributes

Example:

[
  {
    "field": "headcount.total",
    "order": "desc"
  }
]

max_results

integer

default:10000

Total number of records the job will produce. Clamped to the cap of 10,000 — asking for more is silently reduced to the cap, not rejected. Defaults to the cap when omitted. Zero or negative values return 400.

Required range: x >= 1

Example:

500

limit_per_page

integer

default:100

Optional internal page-size hint controlling how many records are fetched per page while the job paginates. It does not limit how many records you get back — use max_results for that.

Example:

100

fields

Optional list of dotted field paths to include in each record (also accepted as a single comma-separated string). When omitted, all fields permitted for your account are returned. Records in the results file contain exactly the requested fields. The selectable fields are the same as the non-batch /company/search endpoint.

Example:

["basic_info.name", "headcount.total"]

webhook_url

string<uri>

Optional URL that receives a POST notification when the job finishes, so you do not have to poll.

Example:

"https://example.com/webhooks/crustdata-batch"

Response

Batch job accepted for processing

Returned immediately when a batch job is accepted. No data is returned at submit time — poll status_url for progress and download links.

batch_id

string<uuid>

required

Unique ID of the batch job. Use it to poll GET /batch/{batch_id}.

Example:

"53ab686b-c054-496b-8baf-baff5ecc85cf"

status

enum<string>

required

Initial job status. Always pending at submit time.

Available options:

pending

Example:

"pending"

entity

enum<string>

required

Entity type the job operates on.

Available options:

company,

person

Example:

"company"

action

enum<string>

required

Internal action name for the job. Live endpoints report enrich_live / search_live.

Available options:

enrich,

enrich_live,

search,

search_live

Example:

"enrich"

identifier_count

integer

required

Number of identifiers submitted. Search jobs always report 1 (the query).

Example:

2

entities_requested

integer

required

Number of entities the job was asked to produce. For enrich jobs this equals identifier_count; for search jobs it is 1 until results are known.

Example:

2

status_url

string

required

Relative URL to poll for the job status (GET /batch/{batch_id}).

Example:

"/batch/53ab686b-c054-496b-8baf-baff5ecc85cf"