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

> Find work emails and phone numbers for one person, a batch of people or a whole list, and pay only for what is found. Verify an email address.

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:

| Value found | By the package | By the waterfall |
| - | - | - |
| A work email | \$0.02 | \$0.05 |
| A phone number | \$0.05 | \$0.10 |

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`.

```bash theme={null}
curl https://api.outbound.dev/v1/people/enrich \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"linkedinUrl": "https://www.linkedin.com/in/ana-costa", "find": "email_and_phone", "providers": "waterfall"}'
```

```json theme={null}
{
  "personId": "6a1f0c2b9d4e8a7f3c5b2e22",
  "emails": [{ "email": "ana@northwind.example", "status": "valid" }],
  "phones": [{ "phoneNumber": "+14155550123", "status": "valid" }],
  "primaryEmail": "ana@northwind.example",
  "primaryPhone": "+14155550123",
  "found": {
    "email": { "email": "ana@northwind.example", "foundBy": "package" },
    "phone": { "phoneNumber": "+14155550123", "foundBy": "waterfall" }
  }
}
```

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

```bash theme={null}
curl https://api.outbound.dev/v1/people/enrich/batch \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"people": [{"personId": "6a1f0c2b9d4e8a7f3c5b2e22"}, {"fullName": "Rui Matos", "companyDomain": "northwind.example"}], "find": "email"}'
```

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

```json theme={null}
{
  "id": "6a1f0c2b9d4e8a7f3c5b2e40",
  "type": "people_enrichment",
  "status": "succeeded",
  "find": "email",
  "providers": "package",
  "progress": { "done": 2, "total": 2 },
  "units": [{ "item": "email_found_package", "units": 1 }],
  "chargedUsd": "0.020000",
  "results": [
    {
      "index": 0,
      "personId": "6a1f0c2b9d4e8a7f3c5b2e22",
      "emails": [{ "email": "ana@northwind.example", "status": "valid" }],
      "phones": [],
      "primaryEmail": "ana@northwind.example",
      "found": { "email": { "email": "ana@northwind.example", "foundBy": "package" } }
    },
    { "index": 1, "error": { "code": "person_not_identifiable", "message": "…" } }
  ],
  "createdAt": "2026-11-15T10:00:00.000Z",
  "finishedAt": "2026-11-15T10:00:40.000Z"
}
```

* **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](https://docs.outbound.dev/guides/build-lists.md)). Then:

```bash theme={null}
curl https://api.outbound.dev/v1/lists/6a1f0c2b9d4e8a7f3c5b2e20/enrich \
  -H "Authorization: Bearer $OUTBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"find": "email_and_phone", "providers": "package", "maxRows": 2000}'
```

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

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

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

**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`](https://docs.outbound.dev/api-reference/enrichment/verify-an-email-address) checks whether one email address can receive mail, without writing to 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" }
```

| `status` | Meaning | Price |
| - | - | - |
| `valid` | The address can receive mail. | \$0.01 |
| `invalid` | It cannot, or it must never be written to: a spam trap, an abuse or a do-not-mail address. | \$0.01 |
| `risky` | Its domain accepts mail for every address, so this one cannot be confirmed. | \$0.01 |
| `unknown` | No verdict could be had. | Free |

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

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


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