Get Started
Start typing to search…

Enrich Contact Emails and Phone Numbers with Waterfall Enrichment

Overview

Apollo's Enrichment API allows you to run waterfall enrichment when calling the People Enrichment or Bulk People Enrichment endpoints.

If at least one waterfall enrichment request parameter is enabled, Apollo returns an immediate synchronous response containing demographic and firmographic information, along with a waterfall enrichment request status. Final waterfall enrichment results, including emails and/or phone numbers, are delivered asynchronously to a configured webhook.

Before You Start

Waterfall enrichment runs based on the global settings set by your admin in the Apollo platform. Make sure to configure your waterfall settings and third-party data sources for [emails](https://app.apollo.io/#/people?waterfall_config_field=email and phone numbers before attempting to run waterfall enrichment via the Apollo API.

Apollo’s API reference docs show the query parameters available for you to use with the Enrichment API. Apollo is going to walk through specific scenarios in this article, but you can address your own cases by combining these examples with the reference information.

Prerequisites

Waterfall enrichment runs successfully via the Apollo Enrichment API when you meet all the conditions below:

  1. At least one waterfall query parameter is enabled

    • run_waterfall_email = true for emails OR
    • run_waterfall_phone = true for phone numbers

    If both are false or absent, the People Enrichment and Bulk People Enrichment endpoints run without waterfall enrichment.

  2. Webhook is available

    • A valid webhook_url must be provided (reachable URL)

  3. Minimum identifiers for best match rates

    • Provide at least one of the following for better matching across your connected third-party data sources :

      • first_name,last_name
      • linkedin_url
      • email

      If minimum identifiers are missing or insufficient, the request may still be accepted, but waterfall enrichment will fail validation or return low or empty match outcomes.

How It Works

To run waterfall enrichment with Apollo's Enrichment API:

  1. Call the People Enrichment or Bulk People Enrichment endpoints with at least one of the following query parameters:
    1. run_waterfall_email = true
    2. run_waterfall_phone = true
  2. The Apollo API returns a synchronous response immediately with demographic and firmographic data, along with a waterfall enrichment status.
  3. Apollo runs waterfall enrichment with your connected data sources until an email or phone number is found.
  4. Apollo returns asynchronous waterfall enrichment results to the provided webhook_url.

Query Parameter Options

You can use the following combinations of query parameters to run waterfall enrichment:

  • Access emails via waterfall enrichment:run_waterfall_email=true, run_waterfall_phone=false
    • Returns email in asynchronous webhook response.
  • Access phone numbers via waterfall enrichment: run_waterfall_email=false, run_waterfall_phone=true
    • Phone number is returned in asynchronous webhook response.
  • Access both emails and phone numbers: run_waterfall_email=true, reveal_phone_number=true
    • Returns both email and phone number ****in asynchronous webhook response.

Response Types

When you run waterfall enrichment, you'll receive both a synchronous response and asynchronous webhook response from the Enrichment API.

Synchronous Response

The synchronous response always returns:

  • All demographic and firmographic fields normally returned by People Enrichment and Bulk People Enrichment endpoints.
  • A waterfall enrichment status.
    • Accepted
    • Failed
    • Partially accepted (applicable for bulk people enrichment only)
  • Error messages if waterfall enrichment did not start or failed validation.
  • Unprocessed attributes that were requested but not processed due to validation or failure.

Asynchronous Response

The asynchronous webhook response always returns:

  • Requested emails or phone numbers and their enrichment status.
  • Execution metadata, including request ID, initiation time, and completion time.
  • A record-level enrichment summary, including:
    • Total records requested
    • Records successfully enriched
    • Records where enrichment was not found
  • Attribute-level enrichment counts, such as:
    • Email records enriched vs not found
    • Phone number records enriched vs not found
  • Data source details for each contact record, including:
    • Data sources attempted during waterfall enrichment
    • Data source response status and messages
    • Values returned by each data source
  • Final waterfall enrichment results after all data source attempts complete.
  • Credit consumption details.

Credits

Calls to the People Enrichment and Bulk People Enrichment endpoints consume credits to provide demographic or firmographic data, as well as emails and phone numbers when requested. Credit usage for waterfall enrichment is based on your team’s global waterfall enrichment settings and connected data sources in Apollo.

Apollo calculates your final credit usage for waterfall enrichment after the asynchronous webhook response. Your credit consumption depends on the type of data you request (emails and/or phone numbers) and the data source that provides it. You won’t use additional credits if Apollo or your connected data sources can’t find an email or phone number. Learn more about Apollo credit costs.

Report on Waterfall Enrichment

Review your waterfall data request log in Apollo to get more granular insights into the results of each enrichment run, including:

  • The number of records enriched
  • The requested enrichment types (email or phone)
  • Which data sources returned enriched data
  • Total credit consumption

Example: Enrich Contact Emails and Phone Numbers with Waterfall

To retrieve contact emails and phone numbers via waterfall enrichment:

  1. Call the People Enrichment endpoint:

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

  2. Add run_waterfall_email = true and run_waterfall_phone = true as query parameters.

  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.

  4. Add your webhook_url key:

    1. Go to https://webhook.site and copy your unique URL.
    2. Insert your unique URL in the webhook_url key

cURL Request

The following shows the example as a cURL request:

curl --location --request POST 'https://api.apollo.io/api/v1/people/match?first_name=tim&last_name=Zheng&run_waterfall_email=true&webhook_url=https%3A%2F%2Fwebhook.site%2Fa2dfa966-47c2-46c9-bba8-fbbba267896d&linkedin_url=http%3A%2F%2Fwww.linkedin.com%2Fin%2Ftim-zheng-677ba010' \
--header 'Cache-Control: no-cache' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'x-api-key: your_api_key' \

Response Details

A successful request returns a 200 response status and JSON data similar to the following response. To see your asynchronous webhook response, go to https://webhook.site/ a few seconds after your synchronous response returns.

// Synchronous response via API
{
    "person": {
        "id": "64a7ff0cc4dfae00013df1a5",
        "first_name": "Tim",
        "last_name": "Zheng",
        "name": "Tim Zheng",
        "linkedin_url": "http://www.linkedin.com/in/tim-zheng",
        "title": "Founder & CEO",
        "photo_url": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
        "twitter_url": null,
        "github_url": null,
        "facebook_url": null,
        "extrapolated_email_confidence": null,
        "headline": "Founder & CEO at Apollo",
        "organization_id": "5e66b6381e05b4008c8331b8",
        // ....other demographic and fomographic info
    },
    "waterfall": {
	        "status": "accepted",
	        "message": "Waterfall enrichment request accepted. Results will be sent to the provided webhook URL.",
	   },
     "request_id": 1039995589705121975
}

// Asynchronous response via webhooks

{
  "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": 0,
  "request_id": "b2735fa1-cb01-4c94-85d8-77eb60aff51d",
  "request_initiated": "2026-01-08T08:05:49Z",
  "request_completed": "2026-01-08T08:10:56Z",
  "people": [
    {
      "id": "695f655dc46b8364aefc80c0",
      "waterfall": {
        "emails": [
          {
            "vendors": [
              {
                "id": "icypeas_single_email_search-1",
                "name": "Icypeas",
                "status": "UNVERIFIED",
                "emails": [
                  "[email protected]"
                ],
                "usedForVerification": false,
                "statusCode": null,
                "statusMessage": null,
                "authMechanism": "native"
              }
            ]
          }
        ],
        "phone_numbers": [
          {
            "vendors": [
              {
                "id": "prospeo_mobile_finder-1",
                "name": "Prospeo",
                "status": "UNVERIFIED",
                "phone_numbers": [
                  "916-787-1122"
                ],
                "usedForVerification": false,
                "statusCode": null,
                "statusMessage": null,
                "authMechanism": "native"
              }
            ]
          }
        ]
      },
      "phone_numbers": [
        {
          "_id": "695f668dc46b8364aefc80fa",
          "confidence_cd": null,
          "dnc_other_info": {},
          "dnc_status_cd": null,
          "dnc_status_updated_at": null,
          "raw_number": "916-787-1122",
          "sanitized_number": "+19167871122",
          "status_cd": "no_status",
          "type_cd": null,
          "id": "695f668dc46b8364aefc80fa",
          "key": "695f668dc46b8364aefc80fa"
        }
      ],
      "emails": [
        {
          "email": "[email protected]",
          "email_source_cd": null,
          "position": 0,
          "email_status_cd": "Verified",
          "extrapolated_email_confidence": null,
          "third_party_data_provider_id": "icypeas_single_email_search",
          "waterfall_enriched_at": "2026-01-08T08:05:50.241Z",
          "vendor_validation_statuses": []
        }
      ]
    }
  ]
}

Failed waterfall enrichment returns the following response:

{
    "person": {
        "id": "64a7ff0cc4dfae00013df1a5",
	      "first_name": null,
        "last_name": null,
        "name": "",
        "linkedin_url": null,
        "title": null,
        "photo_url": null,
        // ....other demographic and fomographic info
    },
    "waterfall": {
          "status": "failed",
          "message": waterfall_error_message,
          "unprocessed_attributes": [
            {
	            "domain": "example.com"
            }
          ]
      },
      "request_id": 1039995589705121975
}

Teams without access to waterfall enrichment will see the following failed response:

{
    "person": {
        "id": "64a7ff0cc4dfae00013df1a5",
        "first_name": "Tim",
        "last_name": "Zheng",
        "name": "Tim Zheng",
        "linkedin_url": "http://www.linkedin.com/in/tim-zheng",
        "title": "Founder & CEO",
        "photo_url": "https://static.licdn.com/aero-v1/sc/h/9c8pery4andzj6ohjkjp54ma2",
        "twitter_url": null,
        "github_url": null,
        "facebook_url": null,
        "extrapolated_email_confidence": null,
        "headline": "Founder & CEO at Apollo",
        "organization_id": "5e66b6381e05b4008c8331b8",
        // ....other demographic and fomographic info
    },
    "waterfall": {
        "status": "failed",
        "message": "Your team does not have permission to run waterfall enrichment."
	   },
	    "request_id": 2532682948037306456
}

Example: Bulk Enrich Contact Emails and Phone Numbers with Waterfall

To retrieve contact emails and phone numbers via waterfall enrichment:

  1. Call the Bulk People Enrichment endpoint:

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

  2. Add run_waterfall_email = true and run_waterfall_phone = true as query parameters.

  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.

  4. Add your webhook_url key:

    1. Go to https://webhook.site and copy your unique url.
    2. Insert your unique URL in the webhook_url key

cURL Request

The following shows an example of a valid cURL request:

curl --request POST \
     --url 'https://api.apollo.io/api/v1/people/bulk_match?run_waterfall_email=true&run_waterfall_phone=true' \
     --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": "tim",
      "last_name": "zheng",
      "name": "tim zheng",
      "linkedin_url": "http://www.linkedin.com/in/tim-zheng-677ba010"
    },
    {
      "first_name": "Ray",
      "last_name": "Li"
    }
  ]
}
'

Response Details

A successful request returns a 200 response status and JSON data similar to the following response. To see your asynchronous webhook response, go to https://webhook.site/ a few seconds after your synchronous response returns.

{
  "status": "success",
  "error_code": null,
  "error_message": null,
  "total_requested_enrichments": 1,
  "matches": [
    {
      "id": "64a7ff0cc4dfae00013df1a5",
      "first_name": "Tim",
      "last_name": "Zheng",
      "name": "Tim Zheng",
      "linkedin_url": "http://www.linkedin.com/in/tim-zheng-677ba010",
			// ....other demographic and fomographic info
		},
		{
      "id": "64a7ff0cc4dfae00013df1a6",
      "first_name": "Ray",
      "last_name": "Li",
      "name": "Ray Li",
      "linkedin_url": "http://www.linkedin.com/in/ray-li-677ba011",
			// ....other demographic and fomographic info
		},
	],
	"waterfall": {
        "status": "accepted",
        "message": "Waterfall enrichment request accepted. Results will be sent to the provided webhook URL.",
    },
    "request_id": 1039995589705121975
}

Partially accepted waterfall enrichment returns the following response:

{
  "status": "success",
  "error_code": null,
  "error_message": null,
  "total_requested_enrichments": 2,
  "matches": [
    {
      "id": "64a7ff0cc4dfae00013df1a5",
      "first_name": "Tim",
      "last_name": "Zheng",
      "name": "Tim Zheng",
      "linkedin_url": "http://www.linkedin.com/in/tim-zheng-677ba010",
			// ....other demographic and fomographic info
		},
		null
	],
	"waterfall": {
        "status": "partial_accepted",
        "message": "Waterfall enrichment request accepted. Some attributes were not processed due to invalid values.",
        "unprocessed_attributes":[
	        null,
          {
            "domain": "ab.com"
          }
        ]
   },
   "request_id": 1039995589705121975
  }

Failed waterfall enrichment returns the following response:

{
  "status": "success",
  "error_code": null,
  "error_message": null,
  "total_requested_enrichments": 1,
  "matches": [
		null,
		null
	],
	"waterfall": {
        "status": "failed",
        "message": waterfall_error_message,
        "unprocessed_attributes": [
	        {
			      "domain": "example.com"
			    },
          {
            "domain": "example1.com"
          }
        ]
    },
    "request_id": 1039995589705121975
  }

Updated 1 day ago

What’s Next