Sign in

v1

latestOpenAPI 3.0.32026-07-222085264.6 KB
Batch APIs

Submit a batch company database search job

Run one company database search query and receive up to 10,000 matching companies as a single results file. Where the non-batch /company/search returns one cursor page per call, the batch job walks every page for you and delivers the entire result set at once.

<Note> An account may have at most 5 active (`pending` or `processing`) batch jobs at a time; submitting a sixth returns `429`. </Note>

Provide one filters group ({op, conditions}) plus optional sorts and max_results. The non-batch paging parameters (limit, page, preview) are ignored by batch jobs — result volume is controlled by max_results alone. Records in the downloaded results file are flat, identical to the non-batch /company/search record shape.

post/batch/company/search

Headers

x-api-version'2025-11-01' required
Example:2025-11-01

API version to use. This endpoint currently requires 2025-11-01.

Request body

max_resultsinteger

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.

limit_per_pageinteger

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.

webhook_urlstring uri

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

Example request

{
  "filters": {
    "op": "and",
    "conditions": [
      {
        "field": "headcount.total",
        "type": ">",
        "value": 1000
      }
    ]
  },
  "max_results": 2,
  "fields": [
    "basic_info.name",
    "basic_info.primary_domain",
    "headcount.total"
  ]
}

Response

Batch job accepted for processing

batch_idstring uuid required

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

status'pending' required

Initial job status. Always pending at submit time.

entity'company' | 'person' | 'social_post' required

Entity type the job operates on.

action'enrich' | 'enrich_live' | 'contact_enrich' | 'search' | 'search_live' required

Internal action name for the job. Live endpoints report enrich_live / search_live; the person contact enrichment endpoint reports contact_enrich.

identifier_countinteger required

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

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

status_urlstring required

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

Example response

{
  "batch_id": "53ab686b-c054-496b-8baf-baff5ecc85cf",
  "status": "pending",
  "entity": "company",
  "action": "enrich",
  "identifier_count": 2,
  "entities_requested": 2,
  "status_url": "/batch/53ab686b-c054-496b-8baf-baff5ecc85cf"
}