Skip to main content
Enrichment finds a person’s work email, phone number or both, and saves the person, with what was found, in your workspace. You pay for each value found. A value the person already had, and a search that finds nothing, cost nothing.

Choose where to look

Every enrichment call takes providers:
  • package (the default) searches our own data package.
  • waterfall searches the package first, then a fixed series of further providers for what the package did not find.
A value’s price depends on who found it: With providers set to package, every value costs the package price. find says what to look for: email (the default), phone or email_and_phone.

What is returned and charged

  • Work emails only. An address is returned and charged only when its check showed valid, or catch-all (the domain accepts mail for any address, so this one could not be confirmed). Personal addresses, and addresses that failed or could not be checked, are left out and never charged.
  • Every phone number found is charged, whatever checking it showed, a company’s main line included. Each is returned with what checking it showed, as its status: hq marks a company’s main line.
  • Values the person already had are returned and cost nothing.

Enrich one person

Name the person one way: by personId (the id of their row in a list), by linkedinUrl, or by a name with companyName or companyDomain.
found holds what this call found that the person did not have, and who found it: exactly what the call was charged for. This one cost $0.12, as the X-Charged-Usd header shows. A waterfall search can take over a minute, so allow two minutes for the answer.

Enrich up to 100 people

POST /v1/people/enrich/batch takes 1 to 100 people, each named one way, with one find and one providers for all of them. It answers 202 with a job:
Follow the job with GET /v1/jobs/{jobId} until status is no longer running. Once it has ended, results lists every person in the order you sent them, answered as POST /v1/people/enrich answers one person, or with an error:
  • The same person sent twice is searched once and charged once.
  • A person’s error is person_not_found, person_not_identifiable, enrichment_in_progress (another call was enriching them), enrichment_failed, or enrichment_not_run (the job ended before it reached them). A person with an error costs nothing.

Enrich a list

For more than 100 people, put them in a list, then enrich the list. Add up to 500 people a call with POST /v1/lists/{listId}/rows, or add people already in your workspace with POST /v1/lists/{listId}/people (see Build lists). Then:
  • It answers 202 with a job of type list_enrichment. Follow it with GET /v1/jobs/{jobId}.
  • maxRows and offset pick the rows: a run takes up to maxRows rows (10,000 at most, and the default) starting offset rows into the list (0 by default), in the list’s order. Enrich a longer list in runs, each with offset where the last one ended: 0, then 10,000, then 20,000.
  • Rows that already hold what find asks for are skipped and cost nothing, but still count toward maxRows.
  • When the job has ended, read what it found from the list’s rows. For example, GET /v1/lists/{listId}/rows with filters={"enrichedEmail": {"include": ["enriched"]}} answers the rows that now have an email.
  • Only people lists can be enriched. A company list answers 422 with people_list_required.

How a job is charged

1

The most it can cost is held

When a batch or a list run starts, the most it can cost is set aside from your balance: each person or row, at the price of every value find asks for, from the providers you chose.A list run of 2,000 rows with email_and_phone and package holds $140. If your available balance cannot cover the hold, the call answers 402 with insufficient_balance, and nothing runs. The start itself costs nothing: its X-Charged-Usd is 0.000000. Starting the same list run again while it is still running answers the same job, charged once. That second start still needs your available balance to cover a second hold, or it answers 402. To retry a start safely, send an Idempotency-Key.
2

It is charged for what it found

When the job ends, it is charged for the values it found, and the rest of the hold is released. GET /v1/jobs/{jobId} then shows units (the values found, by price item) and chargedUsd.
3

A cancelled job pays for what it found before it stopped

POST /v1/jobs/{jobId}/cancel stops a job. The values it found before it stopped stay in your workspace and are charged. The rest of the hold is released. A job that is still starting answers 409 with job_starting: try again in a few seconds.

Verify an email address

POST /v1/emails/verify checks whether one email address can receive mail, without writing to it:
  • A check takes a few seconds, and ends within about 25 seconds. One that gets no verdict in time answers an empty 500 and costs nothing: try again.
  • The price is held before the check runs. When your available balance cannot cover it, the call answers 402 insufficient_balance.
  • It adds nobody to your workspace. The address is checked and its verdict answered, nothing more.
  • To retry a check safely, send an Idempotency-Key.

Keys and limits

  • Keys. Enrichment calls need a key with the enrichment scope that can write. A batch’s results show only to keys that can read enrichment.
  • Rate limits. Enriching one person has its own rate limit of 60 calls a minute and 2,000 a day. Starting batches and list runs shares another, 10 a minute and 200 a day. Verifying an address has its own too, 60 a minute and 5,000 a day.