Skip to main content
You have people already: an event list, a CRM export, a spreadsheet of names and companies. This guide puts them in a list, finds the work emails and phone numbers they lack, and reads the result back out.

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 rowCount with GET /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

  • maxSpendUsd is 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 402 with insufficient_balance.
  • The Idempotency-Key makes 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 offset set to where the last run ended.
5

Wait for the job

The call answers 202 with a job. Read it until its status is no longer running, no faster than every 15 seconds:
When it has ended, 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:
A check costs $0.01 and answers 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:
  1. Run the list with providers set to package. It is the faster search, and it holds less of your balance: $0.02 a row against $0.05.
  2. Count the rows it found nothing for. Ask for one row with filters={"enrichedEmail": {"include": ["no_emails_found"]}} and pageSize=1, and read pagination.total.
  3. If the gap is worth it, run the list again with providers set to waterfall. Only the rows still without an email are searched.
The two runs cost the same as one waterfall run, because each value is priced by who found it. What you gain is seeing what the package found before you pay for the wider search.

What to do next

Start a campaign to the list: see Your first campaign, end to end. Or keep the list current by adding new rows as they arrive and running the enrichment again, which skips everyone already done.