> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crustdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch Enrich Companies
> Enrich up to **10,000 companies** in a single asynchronous job instead of one request per
company. Provide exactly one identifier type — `names`, `domains`,
`professional_network_profile_urls`, or `crustdata_company_ids` — and optionally the `fields`
to include in each record.
An account may have at most 5 active (`pending` or `processing`) batch jobs at a time;
submitting a sixth returns `429`.
The job responds immediately with a `batch_id`. Poll `GET /batch/{batch_id}` (or provide a
`webhook_url`) and download the gzipped JSONL results file when the job completes. Each record
is wrapped in an `{original_identifier, internal_id, data}` envelope, where `data` holds the
company record in the same shape as the non-batch `/company/enrich` response. Identifiers that
cannot be resolved are silently dropped from the results file (compare `entities_requested`
with `entities_fulfilled`).
## OpenAPI
````yaml /openapi-specs/2025-11-01/batch.yaml post /batch/company/enrich
openapi: 3.0.3
info:
title: Batch API
version: '2025-11-01'
description: >
The Batch API is the asynchronous, high-volume alternative to the standard
Company, Person, and Job endpoints.
You submit a single job describing what you want, Crustdata processes it in
the background, and you
download the complete result set as a file. Batch jobs return the same data
and the same record shapes
as the corresponding non-batch endpoints — the difference is scale,
delivery, and convenience.
Every batch job follows the same three-step lifecycle:
1. **Submit** — `POST` to a batch endpoint with your identifiers or query.
The response returns
immediately with a `batch_id`, an initial `status` of `pending`, and a `status_url`. No data is
returned at submit time.
2. **Poll** — `GET /batch/{batch_id}` until `status` reaches `completed` (or
`failed`). Provide a
`webhook_url` at submit time to receive a notification instead of polling.
3. **Download** — completed jobs include a `download_url` (one merged
results file) and `download_urls`
(the same data split into parts). Files are gzipped JSONL — one record per line — and the links
stay valid for 5 days.
**Result-file record shapes**
- **Enrich jobs** (database and live) wrap each record in an envelope:
`{"original_identifier": ..., "internal_id": ..., "data": {...}}`. `original_identifier` echoes the
exact value you submitted and `internal_id` is the resolved Crustdata ID, so you can join results
back to your input list.
- **Search jobs** (database and live) emit flat records identical to the
corresponding non-batch
endpoint's record shape — no envelope.
**Limits and billing**
- An account may have at most **5 active** (`pending` or `processing`) batch
jobs at a time;
submitting a sixth returns `429`.
- The `x-api-version: 2025-11-01` header is required when submitting jobs.
It is not required on the
job status and list endpoints.
- Billing is based on the number of records actually delivered in the
results file
(`entities_fulfilled`), not on how many you requested. Failed jobs are not charged.
servers:
- url: https://api.crustdata.com
description: Production API server
security:
- bearerAuth: []
tags:
- name: Batch APIs
description: >-
Asynchronous, high-volume jobs for enriching and searching companies,
people, and job listings
paths:
/batch/company/enrich:
post:
tags:
- Batch APIs
summary: Submit a batch company enrichment job
description: >
Enrich up to **10,000 companies** in a single asynchronous job instead
of one request per
company. Provide exactly one identifier type — `names`, `domains`,
`professional_network_profile_urls`, or `crustdata_company_ids` — and
optionally the `fields`
to include in each record.
An account may have at most 5 active (`pending` or `processing`) batch jobs at a time;
submitting a sixth returns `429`.
The job responds immediately with a `batch_id`. Poll `GET
/batch/{batch_id}` (or provide a
`webhook_url`) and download the gzipped JSONL results file when the job
completes. Each record
is wrapped in an `{original_identifier, internal_id, data}` envelope,
where `data` holds the
company record in the same shape as the non-batch `/company/enrich`
response. Identifiers that
cannot be resolved are silently dropped from the results file (compare
`entities_requested`
with `entities_fulfilled`).
operationId: submitBatchCompanyEnrich
parameters:
- $ref: '#/components/parameters/ApiVersion'
requestBody:
required: true
description: >-
Exactly one company identifier type, plus optional field selection,
webhook, and chunking options.
content:
application/json:
schema:
$ref: '#/components/schemas/BatchCompanyEnrichRequest'
examples:
enrich_by_domain:
summary: Enrich two companies by domain
value:
domains:
- stripe.com
- openai.com
fields:
- basic_info.name
- basic_info.primary_domain
- headcount.total
responses:
'200':
description: Batch job accepted for processing
content:
application/json:
schema:
$ref: '#/components/schemas/BatchSubmitResponse'
example:
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
'400':
description: >-
Invalid request — bad identifiers, invalid fields, or missing
version header
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_identifier:
summary: No identifier provided
value:
error:
type: invalid_request
message: >-
Exactly one identifier must be provided: names, domains,
professional_network_profile_urls, or
crustdata_company_ids
metadata: []
two_identifier_types:
summary: More than one identifier type provided
value:
error:
type: invalid_request
message: >-
Only one identifier type can be provided. Found:
domains, crustdata_company_ids
metadata: []
invalid_field:
summary: Unsupported value in `fields`
value:
error:
type: invalid_request
message: 'Invalid fields: bogus.field'
metadata:
- available_fields:
- basic_info.name
- basic_info.primary_domain
- headcount.total
missing_version_header:
summary: Missing x-api-version header
value:
error:
type: invalid_request
message: >-
Missing required header: x-api-version. Please set
x-api-version header appropriately.
metadata: []
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Forbidden — your account is not entitled to this batch endpoint
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
type: permission_error
message: You do not have permission to access /batch/company/enrich.
metadata: []
'429':
$ref: '#/components/responses/TooManyActiveJobs'
'500':
$ref: '#/components/responses/InternalError'
components:
parameters:
ApiVersion:
name: x-api-version
in: header
required: true
schema:
type: string
enum:
- '2025-11-01'
default: '2025-11-01'
example: '2025-11-01'
description: >-
API version to use. Batch job submission requires `2025-11-01`; requests
without this header are rejected with `400`.
schemas:
BatchCompanyEnrichRequest:
type: object
description: >
Request body for a batch company enrichment job. Provide exactly one
identifier type —
`names`, `domains`, `professional_network_profile_urls`, or
`crustdata_company_ids`. Providing
none, or more than one, returns `400`. Each identifier list may also be
sent as a single
comma-separated string.
properties:
names:
description: >-
Company names to enrich. Maximum 10,000 identifiers per job — larger
submissions are rejected with `400`.
example:
- Stripe
- OpenAI
oneOf:
- type: string
description: Comma-separated company names.
example: Stripe,OpenAI
- type: array
maxItems: 10000
items:
type: string
description: A company name.
example: Stripe
domains:
description: >-
Company website domains to enrich. Maximum 10,000 identifiers per
job — larger submissions are rejected with `400`.
example:
- stripe.com
- openai.com
oneOf:
- type: string
description: Comma-separated company website domains.
example: stripe.com,openai.com
- type: array
maxItems: 10000
items:
type: string
description: A company website domain.
example: stripe.com
professional_network_profile_urls:
description: >-
Company profile URLs to enrich. Maximum 10,000 identifiers per job —
larger submissions are rejected with `400`.
example:
- https://www.linkedin.com/company/stripe
oneOf:
- type: string
description: Comma-separated company profile URLs.
example: >-
https://www.linkedin.com/company/stripe,https://www.linkedin.com/company/openai
- type: array
maxItems: 10000
items:
type: string
description: A company profile URL.
example: https://www.linkedin.com/company/stripe
crustdata_company_ids:
description: >-
Crustdata company IDs to enrich. Maximum 10,000 identifiers per job
— larger submissions are rejected with `400`.
example:
- 631394
- 631466
oneOf:
- type: string
description: Comma-separated Crustdata company IDs.
example: 631394,631466
- type: array
maxItems: 10000
items:
type: integer
description: A Crustdata company ID.
example: 631394
fields:
description: >
Optional list of dotted field paths to include in each company
record (also accepted as a
single comma-separated string). When omitted, the default
`basic_info` field set is
returned; requested fields are returned in addition to the defaults.
An unsupported value
returns `400` with the full list of selectable fields in
`metadata.available_fields`. The
selectable fields are the same as the non-batch `/company/enrich`
endpoint.
example:
- basic_info.name
- basic_info.primary_domain
- headcount.total
oneOf:
- type: string
description: Comma-separated dotted field paths.
example: basic_info.name,basic_info.primary_domain,headcount.total
- type: array
items:
type: string
description: A dotted field path.
example: headcount.total
webhook_url:
type: string
format: uri
description: >-
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
chunk_size:
type: integer
minimum: 10
maximum: 1000
default: 100
description: >-
Optional internal processing chunk size (number of identifiers per
processing unit). Values outside 10-1000 return `400`.
example: 100
example:
domains:
- stripe.com
- openai.com
fields:
- basic_info.name
- basic_info.primary_domain
- headcount.total
BatchSubmitResponse:
type: object
required:
- batch_id
- status
- entity
- action
- identifier_count
- entities_requested
- status_url
description: >-
Returned immediately when a batch job is accepted. No data is returned
at submit time — poll `status_url` for progress and download links.
properties:
batch_id:
type: string
format: uuid
description: Unique ID of the batch job. Use it to poll `GET /batch/{batch_id}`.
example: 53ab686b-c054-496b-8baf-baff5ecc85cf
status:
type: string
enum:
- pending
description: Initial job status. Always `pending` at submit time.
example: pending
entity:
type: string
enum:
- company
- person
- social_post
description: Entity type the job operates on.
example: company
action:
type: string
enum:
- enrich
- enrich_live
- contact_enrich
- search
- search_live
description: >-
Internal action name for the job. Live endpoints report
`enrich_live` / `search_live`; the person contact enrichment
endpoint reports `contact_enrich`.
example: enrich
identifier_count:
type: integer
description: >-
Number of identifiers submitted. Search jobs always report `1` (the
query).
example: 2
entities_requested:
type: integer
description: >-
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:
type: string
description: Relative URL to poll for the job status (`GET /batch/{batch_id}`).
example: /batch/53ab686b-c054-496b-8baf-baff5ecc85cf
example:
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
ErrorResponse:
type: object
required:
- error
description: >-
Standard error response returned by the Batch API endpoints when a
request fails.
properties:
error:
type: object
required:
- type
- message
description: Error details.
properties:
type:
type: string
enum:
- invalid_request
- authentication_error
- not_found
- insufficient_credits
- permission_error
- rate_limit_error
- internal_error
description: Category of the error.
example: invalid_request
message:
type: string
description: Human-readable error message.
example: >-
Exactly one identifier must be provided: names, domains,
professional_network_profile_urls, or crustdata_company_ids
metadata:
type: array
default: []
description: >-
Additional structured context (for example `available_fields` on
invalid-field errors).
items:
type: object
additionalProperties: true
description: One structured context entry.
example: []
example:
error:
type: invalid_request
message: >-
Exactly one identifier must be provided: names, domains,
professional_network_profile_urls, or crustdata_company_ids
metadata: []
AuthenticationErrorResponse:
type: object
required:
- message
description: >-
Returned by the API gateway when the API key is missing or invalid.
Unlike other errors, this body is not wrapped in an `error` object.
properties:
message:
type: string
description: Human-readable authentication error message.
example: Invalid API key in request
example:
message: Invalid API key in request
responses:
Unauthorized:
description: Unauthorized — invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationErrorResponse'
example:
message: Invalid API key in request
TooManyActiveJobs:
description: >-
Too many active jobs — the account already has 5 batch jobs in `pending`
or `processing` status
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
type: rate_limit_error
message: >-
You already have 5 active batch jobs. Please wait for one to
complete before submitting another.
metadata: []
InternalError:
description: Internal server error — the job could not be started
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error:
type: internal_error
message: Failed to start batch processing. Credits will be refunded.
metadata: []
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key passed as a Bearer token in the Authorization header.
````
## Related topics
- [Batch Company Enrich](/company-docs/enrichment/batch.md)
- [Person Batch Enrich](/person-docs/enrichment/batch-enrich.md)
- [Company Batch Search](/company-docs/search/batch-search.md)
- [Batch Enrich Person](/api-reference/batch-apis/submit-a-batch-person-enrichment-job.md)
- [Batch Contact Enrich](/api-reference/batch-apis/submit-a-batch-person-contact-enrichment-job.md)