---
updatedAt: 2026-07-28T16:56:00.000Z
agentTools:
  projectIndex: https://docs.apollo.io/llms.txt
---

# Enrich Contact Emails and Phone Numbers with Waterfall Enrichment

## Overview

Use waterfall enrichment with the [people enrichment](https://docs.apollo.io/reference/people-enrichment) and [bulk people enrichment](https://docs.apollo.io/reference/bulk-people-enrichment) endpoints to find email addresses and phone numbers through the data sources configured for your team.

Apollo immediately returns demographic and firmographic data with the status of the waterfall request. When waterfall enrichment finishes, Apollo sends the final email or phone results to the webhook URL included in your request.

## Before You Start

Before you run waterfall enrichment via Apollo API:

1. Ask an Apollo admin to [configure waterfall enrichment](https://knowledge.apollo.io/hc/en-us/articles/34071121664781-Use-Waterfall-Enrichment#toc_2) and select the data sources your team should use.
2. Prepare a publicly accessible HTTPS endpoint that can receive webhook requests from Apollo.
3. Collect enough information to identify each person.

For better match rates, provide at least one of the following:

* `first_name` and `last_name`
* `linkedin_url`
* `email`

Requests with missing or insufficient identifiers may be accepted but return no matches or fail validation.

## How Waterfall Enrichment Works

To run waterfall enrichment:

1. Call the people enrichment or bulk people enrichment endpoint.
2. Enable at least one of the following query parameters:
   * `run_waterfall_email=true` to enrich email addresses.
   * `run_waterfall_phone=true` to enrich phone numbers.
3. Include a valid `webhook_url`.
4. Apollo returns an immediate synchronous response with available person data and the waterfall request status.
5. Apollo runs the configured data sources until the waterfall process finishes.
6. Apollo sends the final results to your webhook URL.

Use the following parameter combinations:

| Data to Enrich                    | Query Parameters                                     |
| :-------------------------------- | :--------------------------------------------------- |
| Email addresses                   | `run_waterfall_email=true&run_waterfall_phone=false` |
| Phone numbers                     | `run_waterfall_email=false&run_waterfall_phone=true` |
| Email addresses and phone numbers | `run_waterfall_email=true&run_waterfall_phone=true`  |

If both waterfall parameters are `false` or omitted, the endpoint runs without waterfall enrichment.

## Response Types

Each waterfall enrichment request can produce two responses.

### Synchronous Response

The immediate response can include:

* Demographic and firmographic data normally returned by the enrichment endpoint
* The waterfall request status
* A request ID
* Validation errors
* Attributes Apollo couldn't process

For a single-person request, the waterfall status can be:

* `accepted`
* `failed`

For a bulk request, the status can be:

* `accepted`
* `partial_accepted`
* `failed`

### Asynchronous Webhook Response

When the waterfall process finishes, Apollo sends a webhook response that can include:

* Enriched email addresses or phone numbers
* Request and completion timestamps
* Record-level enrichment totals
* Email and phone enrichment totals
* Data sources attempted for each record
* Statuses and messages returned by each data source
* Final enriched values
* Credit usage

## Credits

People enrichment and bulk people enrichment may use credits for demographic data, email addresses, and phone numbers.

Waterfall enrichment credit usage depends on:

* The data requested
* Your Apollo plan
* Your team's waterfall configuration
* The data sources attempted
* The pricing rules for each data source

Some data sources charge only when they return data. Other data sources may consume credits for a lookup even when they don't find an email address or phone number.

Check out [Apollo API pricing and credits](https://docs.apollo.io/docs/api-pricing) for current API credit guidance. You can also review your team's [waterfall data request log](https://app.apollo.io/#/settings/data-requests/waterfall) to see:

* Records submitted for enrichment
* Requested enrichment types
* Data sources attempted
* Enrichment results
* Credits consumed

## 1: Enrich One Person with Email and Phone Data

To enrich email addresses and phone numbers for one person:

1. Call the people enrichment endpoint:

```http
POST https://api.apollo.io/api/v1/people/match
```

2. Add the following query parameters:

| Parameter             | Value for this Example                   |
| :-------------------- | :--------------------------------------- |
| `first_name`          | `Avery`                                  |
| `last_name`           | `Chen`                                   |
| `linkedin_url`        | `https://www.linkedin.com/in/avery-chen` |
| `run_waterfall_email` | `true`                                   |
| `run_waterfall_phone` | `true`                                   |
| `webhook_url`         | `https://example.com/webhooks/apollo`    |

3. Add the following keys and values to the header of your request:
   1. **Content-Type**: `application/json`
   2. **Cache-Control**: `no-cache`
   3. **x-api-key**: Enter your Apollo API key.

> 📘 Test Your Webhook
>
> To test this workflow before configuring your production endpoint, use a webhook testing service such as [webhook.site](https://webhook.site/) and include the generated HTTPS URL as the `webhook_url`.

### cURL Request

The following shows the example as a cURL request:

```curl
curl --request POST \
     --url 'https://api.apollo.io/api/v1/people/match?first_name=Avery&last_name=Chen&linkedin_url=https%3A%2F%2Fwww.linkedin.com%2Fin%2Favery-chen&run_waterfall_email=true&run_waterfall_phone=true&webhook_url=https%3A%2F%2Fexample.com%2Fwebhooks%2Fapollo' \
     --header 'Cache-Control: no-cache' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY'
```

### Synchronous Response

A successful request returns a `200` response status and JSON data similar to the following response:

```json
{
  "person": {
    "id": "64a7ff0cc4dfae00013df1a5",
    "first_name": "Avery",
    "last_name": "Chen",
    "name": "Avery Chen",
    "linkedin_url": "https://www.linkedin.com/in/avery-chen",
    "title": "VP of Sales",
    "organization_id": "5e66b6381e05b4008c8331b8"
  },
  "waterfall": {
    "status": "accepted",
    "message": "Waterfall enrichment request accepted. Results will be sent to the provided webhook URL."
  },
  "request_id": "1039995589705121975"
}
```

### Asynchronous Webhook Response

When waterfall enrichment finishes, Apollo sends a `POST` request to the provided webhook URL with JSON data similar to the following response:

```json
{
  "status": "success",
  "total_requested_enrichments": 1,
  "target_fields": [
    "emails",
    "phone_numbers"
  ],
  "records_enriched": 1,
  "email_records_enriched": 1,
  "mobile_records_enriched": 1,
  "enrichment_not_found": 0,
  "email_records_not_found": 0,
  "mobile_records_not_found": 0,
  "credits_consumed": 9,
  "request_id": "b2735fa1-cb01-4c94-85d8-77eb60aff51d",
  "request_initiated": "2026-01-08T08:05:49Z",
  "request_completed": "2026-01-08T08:10:56Z",
  "people": [
    {
      "id": "64a7ff0cc4dfae00013df1a5",
      "waterfall": {
        "emails": [
          {
            "vendors": [
              {
                "id": "email_provider-1",
                "name": "Email Provider",
                "status": "VERIFIED",
                "emails": [
                  "avery@example.com"
                ],
                "usedForVerification": false,
                "statusCode": null,
                "statusMessage": null,
                "authMechanism": "native"
              }
            ]
          }
        ],
        "phone_numbers": [
          {
            "vendors": [
              {
                "id": "phone_provider-1",
                "name": "Phone Provider",
                "status": "VERIFIED",
                "phone_numbers": [
                  "+12025550101"
                ],
                "usedForVerification": false,
                "statusCode": null,
                "statusMessage": null,
                "authMechanism": "native"
              }
            ]
          }
        ]
      },
      "phone_numbers": [
        {
          "raw_number": "+1 202-555-0101",
          "sanitized_number": "+12025550101",
          "status_cd": "valid_number",
          "type_cd": "mobile"
        }
      ],
      "emails": [
        {
          "email": "avery@example.com",
          "position": 0,
          "email_status_cd": "Verified",
          "third_party_data_provider_id": "email_provider",
          "waterfall_enriched_at": "2026-01-08T08:10:55.241Z"
        }
      ]
    }
  ]
}
```

The `credits_consumed` value is an example only. Actual usage depends on your plan, waterfall configuration, data requested, and the data sources attempted.

### Failed Request

If Apollo can't start waterfall enrichment, the synchronous response includes a `failed` status and an error message:

```json
{
  "person": {
    "id": null,
    "first_name": null,
    "last_name": null,
    "name": "",
    "linkedin_url": null,
    "title": null
  },
  "waterfall": {
    "status": "failed",
    "message": "Waterfall enrichment couldn't start because the request didn't include sufficient identifying information.",
    "unprocessed_attributes": [
      {
        "domain": "example.com"
      }
    ]
  },
  "request_id": "1039995589705121975"
}
```

### Waterfall Enrichment Not Available

If your team doesn't have access to waterfall enrichment, the response includes the following error:

```json
{
  "person": {
    "id": "64a7ff0cc4dfae00013df1a5",
    "first_name": "Avery",
    "last_name": "Chen",
    "name": "Avery Chen",
    "linkedin_url": "https://www.linkedin.com/in/avery-chen",
    "title": "VP of Sales",
    "organization_id": "5e66b6381e05b4008c8331b8"
  },
  "waterfall": {
    "status": "failed",
    "message": "Your team does not have permission to run waterfall enrichment."
  },
  "request_id": "2532682948037306456"
}
```

## 2: Bulk Enrich People with Email and Phone Data

Use bulk people enrichment to run waterfall enrichment for up to 10 people in one request.

To enrich email addresses and phone numbers for multiple people:

1. Call the bulk people enrichment endpoint:

```http
POST https://api.apollo.io/api/v1/people/bulk_match
```

2. Add the following query parameters:

| Parameter             | Value for this Example                |
| :-------------------- | :------------------------------------ |
| `run_waterfall_email` | `true`                                |
| `run_waterfall_phone` | `true`                                |
| `webhook_url`         | `https://example.com/webhooks/apollo` |

3. Add a `details` array to the request body. Each object in the array represents one person to enrich.

4. Add the following keys and values to the header of your request:
   1. **Content-Type**: `application/json`
   2. **Cache-Control**: `no-cache`
   3. **x-api-key**: Enter your Apollo API key.

### cURL Request

The following shows the example as a cURL request:

```curl
curl --request POST \
     --url 'https://api.apollo.io/api/v1/people/bulk_match?run_waterfall_email=true&run_waterfall_phone=true&webhook_url=https%3A%2F%2Fexample.com%2Fwebhooks%2Fapollo' \
     --header 'Cache-Control: no-cache' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{
       "details": [
         {
           "first_name": "Jordan",
           "last_name": "Patel",
           "linkedin_url": "https://www.linkedin.com/in/jordan-patel"
         },
         {
           "first_name": "Sofia",
           "last_name": "Ramirez",
           "email": "sofia@example.com"
         }
       ]
     }'
```

### Accepted Response

When Apollo accepts all records for waterfall enrichment, the synchronous response contains an `accepted` status:

```json
{
  "status": "success",
  "error_code": null,
  "error_message": null,
  "total_requested_enrichments": 2,
  "matches": [
    {
      "id": "64a7ff0cc4dfae00013df1a5",
      "first_name": "Jordan",
      "last_name": "Patel",
      "name": "Jordan Patel",
      "linkedin_url": "https://www.linkedin.com/in/jordan-patel"
    },
    {
      "id": "64a7ff0cc4dfae00013df1a6",
      "first_name": "Sofia",
      "last_name": "Ramirez",
      "name": "Sofia Ramirez",
      "email": "sofia@example.com"
    }
  ],
  "waterfall": {
    "status": "accepted",
    "message": "Waterfall enrichment request accepted. Results will be sent to the provided webhook URL."
  },
  "request_id": "1039995589705121975"
}
```

### Partially Accepted Response

If Apollo accepts some records but can't process others, the synchronous response contains a `partial_accepted` status. The positions in `unprocessed_attributes` correspond to the positions of the records in the `details` array:

```json
{
  "status": "success",
  "error_code": null,
  "error_message": null,
  "total_requested_enrichments": 2,
  "matches": [
    {
      "id": "64a7ff0cc4dfae00013df1a5",
      "first_name": "Jordan",
      "last_name": "Patel",
      "name": "Jordan Patel",
      "linkedin_url": "https://www.linkedin.com/in/jordan-patel"
    },
    null
  ],
  "waterfall": {
    "status": "partial_accepted",
    "message": "Waterfall enrichment request accepted. Some attributes were not processed due to invalid values.",
    "unprocessed_attributes": [
      null,
      {
        "domain": "invalid.example"
      }
    ]
  },
  "request_id": "1039995589705121975"
}
```

### Failed Response

If Apollo can't start waterfall enrichment for any records, the synchronous response contains a `failed` status:

```json
{
  "status": "success",
  "error_code": null,
  "error_message": null,
  "total_requested_enrichments": 2,
  "matches": [
    null,
    null
  ],
  "waterfall": {
    "status": "failed",
    "message": "Waterfall enrichment couldn't start because the submitted records didn't contain sufficient identifying information.",
    "unprocessed_attributes": [
      {
        "domain": "example.com"
      },
      {
        "domain": "example.org"
      }
    ]
  },
  "request_id": "1039995589705121975"
}
```