# 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.

Canonical guide: <https://engine.neraperla.com/docs/enrichment>

Raw Markdown: <https://engine.neraperla.com/docs/raw/enrichment.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

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`.

```bash
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.

```bash
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](https://engine.neraperla.com/docs/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.
