Batch Identify Person
Resolve a bulk list of emails (business or personal) or professional_network_profile_urls
to the people behind them — reverse email lookup — as a single asynchronous job. This is the
only endpoint whose email resolution matches personal addresses (for example Gmail): the
synchronous /person/enrich and /person/contact/enrich reverse-look-up business emails only,
returning an empty matches array for a personal address.
An account may have at most 5 active (pending or processing) batch jobs at a time;
submitting a sixth returns 429.
Identify is enabled per account. Without access, submits return 403.
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 line is
one record {matched_on, match_type, matches}. This is the same match shape as the
/person/enrich response, not wrapped in the enrich {original_identifier, internal_id, data}
envelope. Each match holds the resolved person’s crustdata_person_id, basic_profile,
social_handles, and updated_at. The person’s profile URL is in
social_handles.professional_network_identifier.profile_url, and its permanent form is in
social_handles.professional_network_identifier.urn_url. An
identifier that resolves to nobody returns an empty matches array and is not billed (compare
entities_requested with entities_fulfilled).
An invalid email does not fail the job. Its row has an empty matches array and an
error_message such as Invalid email: malformed address. You do not pay for it, and
result_count leaves it out. match_type mirrors the identifier key you submitted: email,
business_email, or professional_network_profile_url.
Authorizations
API key passed as a Bearer token in the Authorization header.
Headers
API version to use. Batch job submission requires 2025-11-01; requests without this header are rejected with 400.
2025-11-01 "2025-11-01"
Body
Exactly one identifier type — a list of emails or profile URLs — plus an optional webhook.
Request body for a batch person identify (reverse email lookup) job. Provide exactly one
identifier type — emails, business_emails, or professional_network_profile_urls. Providing
none, or more than one, returns 400. emails accepts business or personal addresses; a
personal address resolves here even though the synchronous endpoints match business emails only.
The endpoint does not accept fields and returns 400 when the body includes it. Every
match returns the same sections.
Emails to reverse-look-up — business or personal addresses. Maximum 300 identifiers per job — larger submissions are rejected with 400. Result rows carry match_type "email".
Emails to reverse-look-up, resolved the same way as emails. Business and personal addresses both resolve. Maximum 300 identifiers per job. Result rows carry match_type "business_email".
Person profile URLs to resolve to their crustdata_person_id. Maximum 300 identifiers per job — larger submissions are rejected with 400.
Optional URL that receives a POST notification when the job finishes, so you do not have to poll.
"https://example.com/webhooks/crustdata-batch"
Response
Batch job accepted for processing
Returned immediately when a batch job is accepted. No data is returned at submit time — poll status_url for progress and download links.
Unique ID of the batch job. Use it to poll GET /batch/{batch_id}.
"53ab686b-c054-496b-8baf-baff5ecc85cf"
Initial job status. Always pending at submit time.
pending "pending"
Entity type the job operates on.
company, person, social_post "company"
Internal action name for the job. Live endpoints report enrich_live / search_live; the person contact enrichment endpoint reports contact_enrich; the person verification endpoint reports verify.
enrich, enrich_live, contact_enrich, search, search_live, verify "enrich"
Number of identifiers submitted. Search jobs always report 1 (the query).
2
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.
2
Relative URL to poll for the job status (GET /batch/{batch_id}).
"/batch/53ab686b-c054-496b-8baf-baff5ecc85cf"