Choose where to look
Every enrichment call takesproviders:
package(the default) searches our own data package.waterfallsearches the package first, then a fixed series of further providers for what the package did not find.
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, orcatch-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:hqmarks a company’s main line. - Values the person already had are returned and cost nothing.
Enrich one person
Name the person one way: bypersonId (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:
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
errorisperson_not_found,person_not_identifiable,enrichment_in_progress(another call was enriching them),enrichment_failed, orenrichment_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 withPOST /v1/lists/{listId}/rows, or add people already in your workspace with POST /v1/lists/{listId}/people (see Build lists). Then:
- It answers
202with a job of typelist_enrichment. Follow it withGET /v1/jobs/{jobId}. maxRowsandoffsetpick the rows: a run takes up tomaxRowsrows (10,000 at most, and the default) startingoffsetrows into the list (0 by default), in the list’s order. Enrich a longer list in runs, each withoffsetwhere the last one ended: 0, then 10,000, then 20,000.- Rows that already hold what
findasks for are skipped and cost nothing, but still count towardmaxRows. - When the job has ended, read what it found from the list’s rows. For example,
GET /v1/lists/{listId}/rowswithfilters={"enrichedEmail": {"include": ["enriched"]}}answers the rows that now have an email. - Only people lists can be enriched. A company list answers
422withpeople_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
500and costs nothing: try again. - The price is held before the check runs. When your available balance cannot cover it, the call answers
402insufficient_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
resultsshow 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.