Batch Contact Enrich - Crustdata Docs

Use this when you need contact data for hundreds of people at once — bulk lists, CRM backfills, or back-office pipelines. Submit a job, then poll or receive a webhook when it finishes. You pay per contact type returned for each matched person — never per candidate record.

Choose this for a higher fill rate. Submit a bulk list and get results as a file, typically within 2–3 minutes. For a quick, synchronous response on a few people, use Contact Enrich instead.

Availability: requires contact-enrich access (enterprise or higher-tier plans). Limits: up to 300 profile URLs per submission.

Pricing

Billed per contact type returned, per matched person — the same prices as Person Contact Enrich, with a maximum of 5 per person.

Contact type returned	Credits per matched person
Business emails	1
Personal emails	2
Phone numbers	2

Counted per type, not per record — a person with four business-email candidates bills once. Persons with no contact data found are not billed for any type. Result rows contain only the contact types you requested; a requested type with no data appears as an empty list. See Pricing for all endpoints.

How it works

Batch contact enrichment is an asynchronous, two-call flow — you submit a job, then fetch the results once it finishes:

Submit your profile URLs

POST /batch/person/contact/enrich with your list of profile URLs and the contact fields you want. You get a batch_id back immediately.

Poll, or wait for a webhook

GET /batch/{batch_id} to check the job status — or pass a webhook_url on submit and we call you when it finishes.

Download the results

Once status is completed, the status response includes a download_url: a gzipped JSONL file with one record per URL, valid for 5 days.

Replace YOUR_API_KEY in each example with your actual API key. All requests require the x-api-version: 2025-11-01 header.

Pricing: no per-profile base fee — you are charged only for the contact values that are delivered. See Pricing for per-field credit costs. Limits: up to 5 active batch jobs per user at a time.

1. Submit your profile URLs

Send your profile URLs in professional_network_profile_urls along with the contact fields you want. The response returns a batch_id immediately — the job runs asynchronously.

curl --request POST \
  --url https://api.crustdata.com/batch/person/contact/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/cassandrebay",
      "https://www.linkedin.com/in/ruchavora"
    ],
    "fields": ["business_email", "personal_contact_info"]
  }'

{
    "batch_id": "c97333e3-046f-4fd2-b888-a5b07793a0ac",
    "status": "pending",
    "entity": "person",
    "action": "contact_enrich",
    "identifier_count": 2,
    "entities_requested": 2,
    "status_url": "/batch/c97333e3-046f-4fd2-b888-a5b07793a0ac"
}

To be notified when the job finishes instead of polling, include a webhook_url in the request body. Crustdata sends a callback to that URL when the batch completes.

2. Get the results

Poll the status_url (or GET /batch/{batch_id}). While the job runs, status is pending or processing. When it is completed, the response includes a download_url.

curl --request GET \
  --url https://api.crustdata.com/batch/c97333e3-046f-4fd2-b888-a5b07793a0ac \
  --header 'authorization: Bearer YOUR_API_KEY' \
  --header 'x-api-version: 2025-11-01'

{
    "batch_id": "c97333e3-046f-4fd2-b888-a5b07793a0ac",
    "status": "completed",
    "entity": "person",
    "action": "contact_enrich",
    "identifier_count": 2,
    "result_count": 2,
    "entities_requested": 2,
    "entities_fulfilled": 2,
    "created_at": "2026-05-28T10:00:00Z",
    "completed_at": "2026-05-28T10:06:00Z",
    "download_url": "https://crustdata-batch-api-data.s3.amazonaws.com/...&X-Amz-Expires=432000"
}

The download_url points to gzipped JSONL (.jsonl.gz) with one record per submitted profile URL. The link is valid for 5 days.

Fields

Request any combination of these contact fields. Only professional network profile URLs are supported as identifiers for this endpoint.

Field	Returns
`business_email`	Verified business email addresses
`personal_contact_info`	Both personal emails and phone numbers
`personal_contact_info.personal_emails`	Personal email addresses only
`personal_contact_info.phone_numbers`	Phone numbers only

Request parameters

Parameter	Type	Required	Description
`professional_network_profile_urls`	string[]	Yes	Profile URLs to enrich. Professional network profile URLs only.
`fields`	string[]	Yes	Which contact fields to enrich (see the table above).
`webhook_url`	string	No	URL to call when the job finishes, instead of polling.

Job lifecycle

Status	Meaning
`pending`	Job accepted, not yet started.
`processing`	Job is running.
`completed`	Job finished — `download_url` is available.
`failed`	Job failed. No contact values were billed.

Errors

Status	Meaning
`400`	Invalid request — missing identifier, invalid field, or no URLs.
`401`	Invalid or missing API key.
`403`	Permission denied or insufficient credits.
`429`	Too many active batch jobs (max 5 per user).
`500`	Internal server error. Retry with exponential backoff.

API reference summary

Detail	Value
Submit	`POST /batch/person/contact/enrich`
Poll	`GET /batch/{batch_id}`
Auth	Bearer token + `x-api-version: 2025-11-01`
Request	`professional_network_profile_urls` (required), `fields` (required). Optional: `webhook_url`.
Response	Submit returns `batch_id` + `status`; poll returns `status` and a `download_url` when complete.
Output	Gzipped JSONL, one record per profile URL, download link valid 5 days.
Errors	`400`, `401`, `403`, `429`, `500`

For credit pricing, see Pricing. For throughput guidance, see Rate limits. See the full API reference for the complete OpenAPI schema.

What to do next

Enrich interactively — Contact Enrich returns contact data synchronously for up to 25 URLs per request.
Find people first — use Person Search to build the list of profile URLs to enrich.

​Pricing

​How it works

​1. Submit your profile URLs

​2. Get the results

​Fields

​Request parameters

​Job lifecycle

​Errors

​API reference summary

​What to do next

Pricing

How it works

1. Submit your profile URLs

2. Get the results

Fields

Request parameters

Job lifecycle

Errors

API reference summary

What to do next