Enrichment
Fill contact and company fields from the platform's data — post identifiers you hold, synchronously or as a batch of up to 1,000.
Enrichment fills contact and company fields from the platform's own data. Post the identifiers
you already hold — say, for a contact in your CRM — and get values back for exactly the fields you
requested, including business-email discovery through work_email. Enrichment has a level that
sets how hard the platform works: lookup (a direct data match) is available now; research and
verify return enrichment_level_unavailable until they ship on these same endpoints.
Enrich contacts synchronously#
Preview operation create_enrichment_v1_enrichments_post enriches 1–10 contacts in one call and
returns the completed result in the response — no polling. Each contact needs email, or
linkedin_url, or full_name plus company_name or company_domain.
curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/enrichments" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: enrich-jane-1" \
--data '{
"level": "lookup",
"contacts": [
{ "full_name": "Jane Doe", "company_domain": "acme.example" }
],
"fields": ["work_email", "person_job_title", "company_industry", "company_headcount"]
}'The result carries one entry per submitted contact, index-aligned. A matched contact reports
match_level (person, or company when only the company was identified — person fields are
never filled from a company-level match) and matched_on (the identifier that matched). Unmatched
contacts return matched: false with no fabricated data and are never charged. Re-read a completed
run with get_enrichment_v1_enrichments__enrichment_id__get inside the 30-day retention window.
Enrich up to 1,000 contacts as a batch#
Preview operation create_enrichment_batch_v1_enrichment_batches_post takes the identical
request shape with a larger contacts array and returns an accepted asynchronous run. Poll
get_enrichment_batch_v1_enrichment_batches__batch_id__get until the run reaches a terminal
state; a succeeded batch carries the same per-contact results array as the synchronous
response.
curl --fail-with-body --silent --show-error \
--request POST "$BLACKPEARL_API_BASE_URL/v1/enrichment-batches" \
--header "Authorization: Bearer $BLACKPEARL_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: enrich-crm-sync-1" \
--data '{
"level": "lookup",
"contacts": [
{ "email": "jane.doe@acme.example" },
{ "full_name": "Alex Chen", "company_name": "Acme Corporation" }
],
"fields": ["work_email", "company_industry"]
}'Fields and billing#
fields is any subset of the lookup catalog: work_email, person_job_title,
person_linkedin_url, company_name, company_domain, company_linkedin_url,
company_description, company_industry, company_headcount, company_revenue, company_city,
company_state, company_zip. Fields that need a higher level — company_latest_funding,
work_email_verification, person_seniority — are rejected at create with
enrichment_fields_unsupported, naming the offending fields. Enrichment never returns personal
emails, phone numbers, or personal locations at any level. (A Prospecting run
can return a contact's phone number in enrichment.phone.)
A contact bills one flat data-record fee only when its result carries a value for at least one
requested field — the result's contacts_billed is that count. Matches that serve no requested
value, unmatched contacts, and failed runs are free. Runs pass the standard admission gates and
appear under the enrichment capability in usage and billing surfaces.