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

# Submit a batch person database search job

`POST /batch/person/search`

Run one person database search query and receive up to **10,000 matching people** as a single
results file. Where the non-batch `/person/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 `/person/search` record shape.

## Headers

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

## Request body

- BatchPersonSearchRequest — Request body for a batch person 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` BatchSearchFilterGroup, 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.
    - `op` 'and' | 'or', required — Boolean operator combining the conditions in this group.
    - `conditions` union[], required — Conditions in this group. Each entry is a single field condition or a nested group.
      - union
        - BatchSearchCondition — A single database search filter condition on one field.
          - `field` string, required — Dotted field path to filter on. Batch search supports the same filter fields as the corresponding non-batch endpoint — see `/person/search` and `/company/search` for the full field catalogs.
          - `type` '=' | '!=' | '<' | '=<' | '>' | '=>' | 'in' | 'not_in' | '(.)' | '(!)' | '[.]' | 'geo_distance', required — Filter operator, identical to the non-batch search operators. Use '=' for exact match, '!=' for not equal, '<' and '>' for exclusive comparisons, '=<' and '=>' for inclusive comparisons, 'in'/'not_in' for set membership (value must be an array), '(.)' for case-insensitive all-words match (a piped value is AND'd across its separate words, not OR), '(!)' for case-insensitive fuzzy negation, '[.]' for case-insensitive exact-phrase match, and 'geo_distance' for geographic radius. NOTE: '(!)', 'geo_distance', and 'geo_exclude' apply to person search only — company search and company batch reject them.
          - `value` union, required — Filter value. The type depends on the operator: a string or number for comparison operators, an array for 'in'/'not_in', a string for the fuzzy and substring operators, and an object with `location` or `lat_lng` plus `distance` and optional `unit` for 'geo_distance'.
            - string
            - number
            - integer
            - boolean
            - union[]
              - …
            - object — Object value used by `geo_distance`. Supply either `location` (geocoded server-side) or `lat_lng` (`[lat, lng]`), plus `distance` and an optional `unit`.
              - …
        - BatchSearchFilterGroup — recursive
  - `sorts` BatchSearchSort[] — Optional sort directives applied to matched people in order, identical to the non-batch `/person/search` `sorts` parameter.
    - `field` string, required — Field path to sort on. The sortable fields are the same as the corresponding non-batch search endpoint.
    - `order` 'asc' | 'desc', required — Sort direction.
  - `max_results` integer — 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_page` integer — 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.
  - `fields` union — 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 `/person/search` 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.

## 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 — missing or malformed filters, or invalid max_results
- `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)