Enrichment is when you refresh existing records so your prospecting data is up-to-date.

Use the bulk people enrichment endpoint to enrich data for up to ten people with a single API call. To enrich data for a single person, use the people enrichment endpoint instead.

Apollo relies on the information you pass via the endpoint's parameters to identify the correct people to enrich. The details for each person should be passed as an object in the details[] array. When you provide more information, Apollo is more likely to find matches within its database. If you only provide general information, such as a name without a domain or email address, you may receive a 200 response, but the response indicates that no records have been enriched. Check match_confidence in the response to understand how confidently Apollo matched the submitted information.

By default, this endpoint doesn't return personal emails or phone numbers. Use the reveal_personal_emails parameter to retrieve personal emails and reveal_phone_number to retrieve phone numbers. If you set either of these parameters to true, Apollo attempts to provide emails or phone numbers for all matches.

When you use reveal_phone_number, a valid webhook_url is required so Apollo can deliver the completed phone enrichment results. Apollo returns the main enrichment response synchronously, then sends the requested phone numbers to the webhook asynchronously. See webhook details.

You can also use the run_waterfall_email and run_waterfall_phone parameters to run waterfall enrichment via this endpoint. Waterfall enrichment gives you broader data coverage by checking connected third-party data sources for contact emails and phone numbers.

When you call this endpoint and include at least one waterfall parameter, a valid webhook_url is required so Apollo can deliver the completed waterfall enrichment results. Apollo returns an immediate synchronous response with demographic and firmographic data, along with a waterfall enrichment request status. Apollo then delivers enriched emails or phone numbers asynchronously to the configured webhook.

Reading the response

The response differs depending on whether you use waterfall enrichment.

For a standard request, the response includes matches along with:

• total_requested_enrichments
• unique_enriched_records
• missing_records
• credits_consumed

Each person in matches also includes match_confidence, which indicates how confidently Apollo matched the submitted information to a person. Possible values are high and none. For standard requests, successfully matched people return match_confidence: high, while unmatched entries are returned as null. When you use waterfall enrichment, an unmatched result can return match_confidence: none.

If you set run_waterfall_email or run_waterfall_phone to true, the response includes a waterfall object instead. Because waterfall enrichment continues asynchronously, unique_enriched_records, missing_records, and credits_consumed aren't included in the initial response. total_requested_enrichments is included in both response types.

When run_waterfall_email is true, the entries in matches also don't include email or email_status. Apollo sends the enriched email data later to your webhook.

Keep the following response fields in mind:

• unique_enriched_records counts the number of distinct people whose enrichment consumed credits. It doesn't represent the number of people returned in matches, so it can be lower than the number of matches or 0 when matches contains results.
• credits_consumed can contain a decimal value depending on your plan's credit pricing.
• request_id is a signed 64-bit integer and may be negative. Pass the value unchanged when you use the poll webhook result endpoint.
• status returns success for a successful 200 response, even when Apollo doesn't match every requested person. Use missing_records and matches to review the enrichment results.

Webhook details

• When using native phone enrichment, the webhook response follows: Native webhook response details.

• When using waterfall enrichment, the webhook response follows: Waterfall webhook response details.

• You can poll webhook results with the poll webhook result endpoint by passing the request_id from the bulk people enrichment response.

Webhook requirements

• HTTPS required: Your endpoint must be publicly accessible over HTTPS.

• Rate limiting: Ensure your webhook endpoint can handle the volume of webhook traffic sent by Apollo.

• Idempotency: Apollo may retry webhook calls. Your endpoint should be idempotent to handle duplicate payloads safely.