---
title: "Submit a batch person enrichment job"
method: POST
path: "/batch/person/enrich"
tags: ["Batch APIs"]
---

# Submit a batch person enrichment job

`POST /batch/person/enrich`

Enrich up to **10,000 people** in a single asynchronous job. Provide exactly one identifier
type — `professional_network_profile_urls` or `business_emails` — and optionally the `fields`
to include in each record.

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

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
person record in the same shape as the non-batch `/person/enrich` response. Identifiers that
cannot be resolved are silently dropped from the results file (compare `entities_requested`
with `entities_fulfilled`).

## Headers

- `x-api-version` '2025-11-01', required

## Request body

- BatchPersonEnrichRequest — Request body for a batch person enrichment job. Provide exactly one identifier type — `professional_network_profile_urls` or `business_emails`. Providing none, or more than one, returns `400`. Each identifier list may also be sent as a single comma-separated string.
  - `professional_network_profile_urls` union — Person profile URLs to enrich. Maximum 10,000 identifiers per job — larger submissions are rejected with `400`.
    - string — Comma-separated person profile URLs.
    - string[]
  - `business_emails` union — Business email addresses to enrich. Maximum 10,000 identifiers per job — larger submissions are rejected with `400`.
    - string — Comma-separated business email addresses.
    - string[]
  - `fields` union — Optional list of dotted field paths to include in each person record (also accepted as a single comma-separated string). When omitted, the default `basic_profile` and `social_handles` field sets are 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 `/person/enrich` endpoint.
    - string — Comma-separated dotted field paths.
    - string[]
  - `webhook_url` string, uri — Optional URL that receives a POST notification when the job finishes, so you do not have to poll.
  - `chunk_size` integer — Optional internal processing chunk size (number of identifiers per processing unit). Values outside 10-1000 return `400`.

## Response `200`

Batch job accepted for processing

- BatchSubmitResponse — 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}`.
  - `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_count` integer, required — Number of identifiers submitted. Search jobs always report `1` (the query).
  - `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.
  - `status_url` string, required — Relative URL to poll for the job status (`GET /batch/{batch_id}`).

## Other responses

- `400` — Invalid request — bad identifiers, invalid fields, or invalid chunk size
- `401` — Unauthorized — invalid or missing API key
- `403` — Forbidden — your account is not entitled to this batch endpoint
- `429` — Too many active jobs — the account already has 5 batch jobs in `pending` or `processing` status
- `500` — Internal server error — the job could not be started

---

[API](https://skmtc.dev/crustdata/apis/batch-api.md) · [All operations](https://skmtc.dev/crustdata/apis/batch-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/crustdata/batch-api/revisions/581689e66ae7/schema)