| Endpoint essentials | |
|---|---|
| API key access | api/v1/people/match or Master API key |
| OAuth scopes | people_match |
| Free account access | Requires an Apollo account registered with a work email address. Additional account eligibility requirements may apply. Paid accounts aren't affected. |
| Credit usage | 1–9 credits per person without waterfall enrichment |
Credits are charged only if credit-consuming data is found: 1 credit for demographics or email, plus 8 credits if a mobile phone is returned. If no credit-consuming data is found, the request consumes 0 credits. Demographic credit usage depends on match_confidence. Apollo doesn't charge a demographic credit when match_confidence is none. When match_confidence is low, Apollo charges a demographic credit only if it returns data you didn't send. Email and mobile phone credit usage isn't determined by match_confidence. Learn more about API pricing and credits.If waterfall enrichment is used for phone or email, credit usage depends on the returned data and the vendors included in your waterfall enrichment configuration; some vendors consume credits per lookup even when no data is found. | |
Enrichment is when you refresh existing records so your prospecting data is up-to-date.
Use the people enrichment endpoint to enrich data for one person. To enrich data for up to ten people with a single API call, use the bulk people enrichment endpoint instead.
Apollo relies on the information you pass via the endpoint's parameters to identify the correct person to enrich. If you provide more information about a person, Apollo is more likely to find a match within its database. If you only provide general information, such as a name without a domain or email address, you might 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:
high: Apollo found a high-confidence match for the submitted person information.medium: Apollo identified a likely match with medium confidence.low: Apollo identified a possible match with low confidence.none: Apollo couldn't find a match for the submitted person information.
By default, this endpoint doesn't return personal emails or phone numbers. Use the reveal_personal_emails and reveal_phone_number parameters to retrieve emails and phone numbers. When you use reveal_phone_number, provide a valid webhook_url so Apollo can deliver completed phone enrichment results. Alternatively, set poll_only=true and poll webhook results with the top-level request_id_str. Poll only when phone_enrichment.status is pending. Do not use phone_enrichment.request_id. If the status is skipped or not_attempted, Apollo did not create a phone enrichment job and polling returns 404 request_id_unknown.
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.
Apollo returns the main enrichment response synchronously, then sends the requested phone numbers to the webhook asynchronously or makes them available to poll, depending on your request. For a pending phone enrichment request, poll webhook results with the top-level request_id_str from the people enrichment response.
You can also use the run_waterfall_email and run_waterfall_phone parameters to run waterfall enrichment. Waterfall enrichment gives you broader data coverage by checking connected third-party data sources for contact emails and phone numbers. When your request includes a waterfall parameter, provide a valid webhook_url. Alternatively, set poll_only=true and poll webhook result with the top-level request_id_str returned by the response. Passing poll_only=true together with webhook_url returns a 400 error (WEBHOOK_URL_WITH_POLL_ONLY). Apollo then returns an immediate synchronous response with demographic and firmographic data, along with a waterfall enrichment request status. Apollo delivers enriched emails or phone numbers asynchronously to the configured webhook or makes them available to poll, depending on your request.