What a row needs
A list takes a row with as little as a name or an email. Enrichment needs more, to know who the person is:
A row with less, such as a first name alone, gives too little to find the person. It costs nothing, since a row is charged only for what is found.
1
Make a list
2
Add your people as rows
Send up to 500 rows a call. For a longer file, send it in batches of 500:Adding rows is free and looks nothing up. Two things to know:
- Every row becomes a new person. A batch sent twice adds everyone twice, so keep track of which batches went through. When a call fails and you cannot tell whether it landed, read the list’s
rowCountwithGET /v1/lists/{listId}before sending it again. - An email you send is kept as it is, unchecked. Enrichment looks only for what a row lacks, so a row that already has an email is left alone.
3
Choose what to find, and where
find says what to look for, and providers where:These are the most a row can cost.
package searches our own data. waterfall searches it first, then a series of further providers for what it did not find: it finds more, takes longer, and costs more when one of those providers is the one that finds a value.A row is charged only for what is found. A row that already has what you asked for is skipped and costs nothing.4
Enrich the list
maxSpendUsdis your ceiling. A run that could cost more is refused before anything starts.- The most it can cost is set aside first. 500 rows at $0.02 hold $10 of your balance until the run ends, then you are charged for what was found and the rest is released. A balance that cannot cover the hold answers
402withinsufficient_balance. - The
Idempotency-Keymakes a retry safe. If the answer is lost, send the same call with the same key and the run starts once. See Idempotency. - A run takes up to 10,000 rows. For a longer list, run it again with
offsetset to where the last run ended.
5
Wait for the job
The call answers When it has ended,
202 with a job. Read it until its status is no longer running, no faster than every 15 seconds:units holds what was found, by price, and chargedUsd what the run cost. To stop a run early, call POST /v1/jobs/{jobId}/cancel: what it found before it stopped is kept and charged, and the rest of the hold is released.6
Read the results
What was found is on the list’s rows. Ask for the rows that now have an email:Each row carries the person’s name, title, company, emails and phones. A page holds up to 1,000 rows. For the next one, send
pagination.nextCursor as cursor, until there is none. See Pagination.Check the addresses you brought
Enrichment returns only addresses that checked out. An address from your own file was never checked. Before you write to one, verify it:valid, invalid, risky or unknown. An unknown is free. Take the addresses that come back invalid out before you write to the list. See Verify an email address.
Start with the package, then decide
A row that already has what you asked for is skipped and costs nothing. That makes two runs a safe way to work:- Run the list with
providersset topackage. It is the faster search, and it holds less of your balance: $0.02 a row against $0.05. - Count the rows it found nothing for. Ask for one row with
filters={"enrichedEmail": {"include": ["no_emails_found"]}}andpageSize=1, and readpagination.total. - If the gap is worth it, run the list again with
providersset towaterfall. Only the rows still without an email are searched.