Person Batch Enrich - Crustdata Docs

Batch enrichment takes a list of identifiers you already have and returns the enriched record for each as a single results file, instead of one Person Enrich call per person. This page covers two endpoints:

Batch enrich — records served from the indexed database, with higher caps and faster turnaround.
Batch live enrich — each profile retrieved fresh from the web at request time.

Batch enrich

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

For profiles retrieved fresh from the web at request time, see Batch live enrich below.

Database batch enrichment

POST /batch/person/enrich takes up to 10,000 values in professional_network_profile_urls. Missing and over-cap submissions are rejected. The identifier list also accepts a single comma-separated string.

curl --request POST \
  --url https://api.crustdata.com/batch/person/enrich \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile.name", "basic_profile.headline", "basic_profile.current_title"]
  }'

{
    "batch_id": "22f80b2b-e5bd-480b-86cc-29f79dc6c821",
    "status": "pending",
    "entity": "person",
    "action": "enrich",
    "identifier_count": 1,
    "entities_requested": 1,
    "status_url": "/batch/22f80b2b-e5bd-480b-86cc-29f79dc6c821"
}

When the job completes, each line in the downloaded file is one person wrapped in the enrichment envelope:

One record from the results file

{
    "original_identifier": "https://www.linkedin.com/in/dvdhsu/",
    "internal_id": 14540,
    "data": {
        "basic_profile": {
            "name": "David Hsu",
            "headline": "Founder, CEO @ Retool",
            "current_title": "Founder, CEO"
        },
        "social_handles": {
            "professional_network_identifier": {
                "profile_url": "https://www.linkedin.com/in/dvdhsu"
            }
        },
        "crustdata_person_id": 14540
    }
}

Record trimmed for clarity.

Fields: requested plus defaults

fields accepts dotted leaf paths, whole family names (basic_profile), or a comma-separated string of either. A family name expands to its entire subtree. The response contains the requested fields plus the default families (basic_profile and social_handles) — matching the non-batch Person Enrich exactly, including the selectable field list. An unsupported value returns 400 with every selectable field in metadata.available_fields.

`chunk_size`

Optional internal processing chunk size (identifiers per processing unit), 10–1000, default 100. Out-of-range values return 400 with "chunk_size must be between 10 and 1000".

Errors

400 — no identifier

{
    "error": {
        "type": "invalid_request",
        "message": "Exactly one identifier must be provided: professional_network_profile_urls",
        "metadata": []
    }
}

400 — chunk_size out of range

{
    "error": {
        "type": "invalid_request",
        "message": "chunk_size must be between 10 and 1000",
        "metadata": []
    }
}

Batch live enrich

Live enrichment is an add-on. If your plan doesn’t include it, contact your Crustdata account team to enable it.

Batch live enrichment takes a list of profile URLs you already have and returns the enriched record for each as a single results file, with each profile retrieved fresh from the web at request time — instead of one Person Live Enrich call per person.

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

For records served from the indexed database — higher caps and faster — see Batch enrich above.

Live batch enrichment

POST /batch/person/professional_network/enrich/live retrieves each profile fresh from the web at request time. Use it when you need the latest title, headline, or employment data and the database record is not recent enough. Key differences from database enrichment:

Profile URLs only. professional_network_profile_urls is the only identifier type — anything else returns 400.
Cap of 300 per job (instead of 10,000). Larger submissions are rejected with 400.
Slower. Expect seconds per profile; live jobs are the most likely to end failed with an error_message.
internal_id echoes the URL. In the envelope, internal_id is the submitted profile URL — not the numeric Crustdata ID.

curl --request POST \
  --url https://api.crustdata.com/batch/person/professional_network/enrich/live \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --header 'x-api-version: 2025-11-01' \
  --data '{
    "professional_network_profile_urls": ["https://www.linkedin.com/in/dvdhsu/"],
    "fields": ["basic_profile.name", "basic_profile.current_title", "basic_profile.headline"]
  }'

{
    "batch_id": "1a5786e5-0e9a-4d58-b55d-7df6f40ecdff",
    "status": "pending",
    "entity": "person",
    "action": "enrich_live",
    "identifier_count": 1,
    "entities_requested": 1,
    "status_url": "/batch/1a5786e5-0e9a-4d58-b55d-7df6f40ecdff"
}

Note the action is enrich_live — that’s how live jobs are labeled wherever you poll or list jobs.

One record from the results file

{
    "original_identifier": "https://www.linkedin.com/in/dvdhsu/",
    "internal_id": "https://www.linkedin.com/in/dvdhsu/",
    "data": {
        "basic_profile": {
            "name": "David Hsu",
            "current_title": "Founder, CEO",
            "headline": "Founder, CEO @ Retool"
        },
        "social_handles": {
            "professional_network_identifier": {
                "profile_url": "https://www.linkedin.com/in/dvdhsu"
            }
        }
    }
}

Record trimmed for clarity. For single-profile live enrichment without the batch lifecycle, see Person Live Enrich.

Fields: requested plus defaults

fields accepts dotted leaf paths, whole family names (basic_profile), or a comma-separated string of either. A family name expands to its entire subtree. The response contains the requested fields plus the default families (basic_profile and social_handles) — matching the non-batch Person Live Enrich exactly. An unsupported value returns 400 with every selectable field in metadata.available_fields.

Errors

400 — wrong identifier type on live enrich

{
    "error": {
        "type": "invalid_request",
        "message": "professional_network_profile_urls must be provided for live enrich",
        "metadata": []
    }
}

400 — more than 300 URLs on live enrich

{
    "error": {
        "type": "invalid_request",
        "message": "Maximum 300 identifiers allowed for person/enrich_live. Found 301",
        "metadata": []
    }
}

What to do next

Need the freshest data? — see Batch live enrich above for profiles retrieved from the web at request time.
Higher caps, faster — see Batch enrich above for records served from the indexed database.
Find people first — see Batch Person Search to turn one query into an input list.
Find people first (live) — see Batch Person Live Search to turn one query into an input list.
Single-person enrichment — see Person Enrich.
Single-profile live enrichment — see Person Live Enrich.
Valid fields values — see the enrich reference.
Enrich companies in batch — see Batch Company Enrich.
Full schema — see the API reference.

​Batch enrich

​Database batch enrichment

​Fields: requested plus defaults

​chunk_size

​Errors

​Batch live enrich

​Live batch enrichment

​Fields: requested plus defaults

​Errors

​What to do next

Batch enrich

Database batch enrichment

Fields: requested plus defaults

`chunk_size`

Errors

Batch live enrich

Live batch enrichment

Fields: requested plus defaults

Errors

What to do next