> ## Documentation Index
> Fetch the complete documentation index at: https://docs.outbound.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Enrich leads you already have

> Take a spreadsheet or a CRM export, find the missing work emails and phone numbers, and pay only for what is found.

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:

| What you have | Send it as |
| - | - |
| A LinkedIn profile | `linkedinUrl` |
| A name and where they work | `firstName`, `lastName` and `companyDomain` or `companyName` |

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**

```bash theme={null}
curl https://api.outbound.dev/v1/lists \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Lisbon logistics summit"}'
```

```json theme={null}
{ "id": "6a1f0c2b9d4e8a7f3c5b2e20", "name": "Lisbon logistics summit", "type": "people", "rowCount": 0, "createdAt": "2026-11-14T10:05:00.000Z" }
```

**2. Add your people as rows**

Send up to 500 rows a call. For a longer file, send it in batches of 500:

```bash theme={null}
curl https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/rows \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows": [{"firstName": "Ana", "lastName": "Costa", "companyName": "Northwind Freight", "companyDomain": "northwind.example", "jobTitle": "Head of Operations"}, {"linkedinUrl": "https://www.linkedin.com/in/rui-almeida"}]}'
```

```json theme={null}
{ "addedCount": 2, "personIds": ["6a1f0c2b9d4e8a7f3c5b2e22", "6a1f0c2b9d4e8a7f3c5b2e23"] }
```

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:

| `find` | `package` | `waterfall` |
| - | - | - |
| `email` | \$0.02 | \$0.05 |
| `phone` | \$0.05 | \$0.10 |
| `email_and_phone` | \$0.07 | \$0.15 |

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**

```bash theme={null}
curl https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/enrich \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c9d2e-8a4b-4e7c-9f30-6b2a1d8e4c75" \
  -d '{"find": "email", "providers": "package", "maxSpendUsd": 20}'
```

* **`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](https://docs.outbound.dev/idempotency.md).
* **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:

```bash theme={null}
curl https://api.outbound.dev/v1/jobs/6a1f0c2b9d4e8a7f3c5b2e14 \
  -H "Authorization: Bearer $OUTBOUND_API_KEY"
```

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:

```bash theme={null}
curl -G https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/rows \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  --data-urlencode 'filters={"enrichedEmail": {"include": ["enriched"]}}' \
  --data-urlencode 'pageSize=1000'
```

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](https://docs.outbound.dev/pagination.md).

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

```bash theme={null}
curl https://api.outbound.dev/v1/emails/verify \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana.costa@example.com"}'
```

```json theme={null}
{ "email": "ana.costa@example.com", "status": "valid" }
```

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](https://docs.outbound.dev/guides/enrich-people.md#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](https://docs.outbound.dev/guides/first-campaign.md). Or keep the list current by adding new rows as they arrive and running the enrichment again, which skips everyone already done.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.