Get Started
Get API key

Enrich Contact Emails and Phone Numbers with Waterfall Enrichment

Overview

Use waterfall enrichment with the people enrichment and 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 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 EnrichQuery Parameters
Email addressesrun_waterfall_email=true&run_waterfall_phone=false
Phone numbersrun_waterfall_email=false&run_waterfall_phone=true
Email addresses and phone numbersrun_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 for current API credit guidance. You can also review your team's waterfall data request log 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:
POST https://api.apollo.io/api/v1/people/match
  1. Add the following query parameters:
ParameterValue for this Example
first_nameAvery
last_nameChen
linkedin_urlhttps://www.linkedin.com/in/avery-chen
run_waterfall_emailtrue
run_waterfall_phonetrue
webhook_urlhttps://example.com/webhooks/apollo
  1. 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 and include the generated HTTPS URL as the webhook_url.

cURL Request

The following shows the example as a cURL request:

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:

{
  "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:

{
  "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": [
                  "[email protected]"
                ],
                "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": "[email protected]",
          "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:

{
  "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:

{
  "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:
POST https://api.apollo.io/api/v1/people/bulk_match
  1. Add the following query parameters:
ParameterValue for this Example
run_waterfall_emailtrue
run_waterfall_phonetrue
webhook_urlhttps://example.com/webhooks/apollo

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

  2. 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 --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": "[email protected]"
         }
       ]
     }'

Accepted Response

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

{
  "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": "[email protected]"
    }
  ],
  "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:

{
  "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:

{
  "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"
}

Updated about 8 hours ago

What’s Next

Did this page help you?