Person Batch Search - Crustdata Docs

Batch search runs one query asynchronously and delivers the entire result set as a single file. Where Person Search returns one cursor page per call, a batch job walks every page for you. This page covers two batch endpoints:

Batch search — results served from the indexed database, with higher caps and faster turnaround.
Batch live search — results retrieved from the web in real time, fresher but with lower caps and slower.

Batch search

POST https://api.crustdata.com/batch/person/search

How batch search differs from non-batch search

One query, whole result set. You submit a single query; the job paginates server-side until max_results is reached or the matches run out.
max_results is the only volume control. It clamps to 10,000 and defaults to that cap when omitted. Values above the cap are silently clamped; zero or negative values return 400. The non-batch paging knobs — limit, page, preview — are silently ignored.
Flat records. Each line in the results file has exactly the non-batch search record shape. No envelope.
Exact field projection. When you pass fields, each record contains exactly those fields — nothing more. Omit fields to get every field your account can read.

Database batch search

POST /batch/person/search takes the same filter fields and operators as Person Search, with one extra rule: the top level of filters must be an {op, conditions} group — a bare {field, type, value} condition is rejected with 400.

curl --request POST \
  --url https://api.crustdata.com/batch/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        {"field": "experience.employment_details.current.title", "type": "(.)", "value": "engineer"}
      ]
    },
    "max_results": 2,
    "fields": ["basic_profile.name", "basic_profile.current_title"]
  }'

{
    "batch_id": "a9afc353-8876-4e64-8b84-02a599561021",
    "status": "pending",
    "entity": "person",
    "action": "search",
    "identifier_count": 1,
    "entities_requested": 1,
    "status_url": "/batch/a9afc353-8876-4e64-8b84-02a599561021"
}

Search jobs always report identifier_count: 1 — the one query. When the job completes, the downloaded file contains flat records with exactly the requested fields:

The results file (all records)

{"basic_profile": {"current_title": "Principal Software Engineer", "name": "Man Sum Simon Yuen"}}
{"basic_profile": {"current_title": "Knowledge Systems Architect · Context Engineer", "name": "Emily Anderson"}}

Nest groups for or-logic

Groups nest inside conditions. This finds engineers in either the United States or Canada:

curl --request POST \
  --url https://api.crustdata.com/batch/person/search \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": {
      "op": "and",
      "conditions": [
        {"field": "experience.employment_details.current.title", "type": "(.)", "value": "engineer"},
        {
          "op": "or",
          "conditions": [
            {"field": "basic_profile.location.country", "type": "=", "value": "United States"},
            {"field": "basic_profile.location.country", "type": "=", "value": "Canada"}
          ]
        }
      ]
    },
    "max_results": 2,
    "fields": ["basic_profile.name", "basic_profile.location.country"]
  }'

{"basic_profile": {"location": {"country": "United States"}, "name": "Emily Anderson"}}
{"basic_profile": {"location": {"country": "United States"}, "name": "Michael Phillips"}}

Exact-match values must match the indexed value — both "United States" and "United States of America" exist as basic_profile.location.country values. Use an or group or Person Autocomplete to discover indexed values first.

Two warnings before you submit large jobs

Unknown filter field names are not rejected at submit time the way non-batch search rejects them — a typo in field simply produces a job that completes with 0 results. Double-check field names against the search reference first.

Do not pass a non-empty sorts array — the job will complete with 0 results. Sort the downloaded file instead, for example jq -s 'sort_by(.basic_profile.name) | .[]' results.jsonl.

Errors

400 — no filters

{
    "error": {
        "type": "invalid_request",
        "message": "`filters` must be provided for search",
        "metadata": []
    }
}

400 — bare condition instead of a group

{
    "error": {
        "type": "invalid_request",
        "message": "Invalid filter shape: [{'type': 'missing', 'loc': ('op',), 'msg': 'Field required', ...}]",
        "metadata": []
    }
}

400 — search URL on a database search

{
    "error": {
        "type": "invalid_request",
        "message": "`professional_network_search_url` is only valid for live search",
        "metadata": []
    }
}

Batch live search

Batch live search is available to accounts with the live entitlement. The Batch search endpoint above is generally available.

POST https://api.crustdata.com/batch/person/professional_network/search/live

Batch live search runs one query asynchronously and delivers the entire result set as a single file, with results retrieved from the web in real time. Where Person Live Search returns one cursor page per call, a batch job walks every page for you. For results served from the indexed database — higher caps and faster — see Batch search above.

How batch live search differs from non-batch search

One query, whole result set. You submit a single query; the job paginates server-side until max_results is reached or the matches run out.
max_results is the only volume control. It clamps to 1,000 and defaults to that cap when omitted. Values above the cap are silently clamped; zero or negative values return 400. The non-batch paging knobs — limit, page, preview — are silently ignored.
Flat records. Each line in the results file has exactly the non-batch search record shape. No envelope.
Exact field projection. When you pass fields, each record contains exactly those fields — nothing more. Omit fields to get every field your account can read.

Live batch search

POST /batch/person/professional_network/search/live retrieves results from the web in real time — fresher than the database, capped at 1,000 records per job, fetched internally in pages of 25, and slower. Live jobs are the most likely to end failed with an error_message. Live filters use a flat list of {field, type, value} objects — not the {op, conditions} group — and field takes an uppercase filter type instead of a dotted path:

curl --request POST \
  --url https://api.crustdata.com/batch/person/professional_network/search/live \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "filters": [
      {"field": "CURRENT_TITLE", "type": "in", "value": ["Software Engineer"]},
      {"field": "REGION", "type": "in", "value": ["United States"]}
    ],
    "max_results": 2,
    "fields": ["basic_profile.name", "basic_profile.headline"]
  }'

{
    "batch_id": "65de822c-f7d3-4b4c-af89-ef683704889e",
    "status": "pending",
    "entity": "person",
    "action": "search_live",
    "identifier_count": 1,
    "entities_requested": 1,
    "status_url": "/batch/65de822c-f7d3-4b4c-af89-ef683704889e"
}

The results file (all records)

{"basic_profile": {"headline": "Full-Stack Software Developer | Spring Boot | Angular | MySQL | Java | TypeScript | US Citizen", "name": "Sael Torres - Diaz"}}
{"basic_profile": {"headline": "Software Engineer - Frontend / Backend / TypeScript / JavaScript / React / Nest.js / Angular / Spring. Authorized to work in the USA without a current/future sponsorship.", "name": "Daniel Ignatyev"}}

Valid filter types: CURRENT_COMPANY, PAST_COMPANY, CURRENT_TITLE, PAST_TITLE, SCHOOL, COMPANY_HEADQUARTERS, COMPANY_HEADCOUNT, COMPANY_TYPE, FUNCTION, INDUSTRY, NUM_OF_FOLLOWERS, REGION, SENIORITY_LEVEL, YEARS_AT_CURRENT_COMPANY, YEARS_IN_CURRENT_POSITION, YEARS_OF_EXPERIENCE, FOLLOWER_OF, CONNECTION_OF, KEYWORD_COMPANY, KEYWORD_FIRST_NAME, KEYWORD_LAST_NAME, KEYWORD_SCHOOL, KEYWORD_TITLE, NETWORK_DEGREE, PROFILE_LANGUAGE, SERVICE_CATEGORY, CONTACT_INTEREST — the same filters as the non-batch Person Live Search, which documents per-filter value formats. An unknown filter type returns 400 listing the valid values. Instead of filters, you can replay a saved people search URL:

Request body

{
    "professional_network_search_url": "https://www.linkedin.com/sales/search/people?query=...",
    "max_results": 100
}

Provide either filters or professional_network_search_url — omitting both returns 400.

Errors

400 — neither filters nor a search URL

{
    "error": {
        "type": "invalid_request",
        "message": "Either `filters` or `professional_network_search_url` must be provided for live search",
        "metadata": []
    }
}

400 — group instead of a flat list

{
    "error": {
        "type": "invalid_request",
        "message": "`filters` for live search must be a list of {field, type, value} objects",
        "metadata": []
    }
}

What to do next

Build queries interactively first — iterate with Person Search or Person Live Search page by page, then submit the final query as a batch job.
Look up operators and fields — see the search reference.
Enrich the people you found — see Batch Person Enrich or Batch Person Live Enrich.
Search companies in batch — see Batch Company Search or Batch Company Live Search.
Search jobs in batch — see Batch Job Search.
Full schema — see the API reference.

​Batch search

​How batch search differs from non-batch search

​Database batch search

​Nest groups for or-logic

​Two warnings before you submit large jobs

​Errors

​Batch live search

​How batch live search differs from non-batch search

​Live batch search

​Errors

​What to do next

Batch search

How batch search differs from non-batch search

Database batch search

Nest groups for or-logic

Two warnings before you submit large jobs

Errors

Batch live search

How batch live search differs from non-batch search

Live batch search

Errors

What to do next