| Endpoint essentials | |
|---|---|
| API key access | api/v1/enrich/create or Master API key |
| OAuth scopes | Not supported |
| Plan access | Requires a workspace on unified credits. Workspaces on a legacy credit plan receive a 403. |
| Credit usage | 8 or 20 credits per phone number, depending on plan, up to 1 credit per email address |
Credits are charged for each row Apollo checks, whatever the verdict: 8 credits per phone number (20 on some earlier unified credit plans) and 1 credit per email address, including a not_validated result. An email check that the validator can't resolve costs 0 credits. Rows rejected in the 202 response, rows that fail before the check runs, and checks that the validator fails to run also cost 0 credits.Before the checks run, Apollo confirms that you have enough credits for every accepted row. If you don't, no row is checked, each row returns a credit_limit_exceeded error, and the request consumes 0 credits.Apollo stores each result for 30 days. If you check the same phone number or email address again within 30 days, you receive the stored result and the check is still charged. A value repeated inside one request is checked and charged once per row. Learn more about API pricing and credits, or review credit usage in Apollo. | |
Validation checks whether an email address or phone number you already have is still good, so you can clean a list before you use it. Apollo runs the same validators that waterfall enrichment uses to verify the emails and phone numbers it finds.
Use this endpoint to validate up to 10 email addresses or up to 10 phone numbers in one request. Set action to email_verifier or phone_verifier, set action_type to tool, and pass one object per value in the input_attributes array: {"email": "..."} for email addresses, or {"phone_number": "..."} for phone numbers. One request validates one kind of value.
This endpoint checks values you send. It doesn't find new email addresses or phone numbers, and it doesn't check Do Not Call registry status. To find contact details for a person, use the bulk people enrichment endpoint.
Validators
Apollo picks the validator for each action. Today, this endpoint uses these validators:
action | Validator |
|---|---|
email_verifier | LeadMagic |
phone_verifier | Trestle |
Apollo plans to support more validators later. Each result names the validator that answered in its validator field.
Getting the results
Validation runs in the background. This endpoint returns 202 Accepted with a request_id and one entry per submitted row, in the order you sent them. Each entry has a status of accepted or rejected. Accepted entries carry a record_id, and rejected entries carry errors. A rejected row is never checked and costs nothing. The request status is accepted when every row was accepted and partially_accepted when some were rejected. If every row is rejected, the endpoint returns a 422 with status: rejected.
Send exactly one of these delivery options:
webhook_url: Apollo sends the results to this HTTPS URL when the checks finish. The URL must resolve to a public address. If delivery fails, Apollo retries it up to 3 times. A4xxresponse other than408or429isn't retried.poll_only: true: Apollo doesn't send a webhook. Pass therequest_idto the poll webhook result endpoint. While the checks run, it returns a404witherror_code: result_pendingandretry_after_seconds. Wait that many seconds, then poll again.
Both options deliver the same result object, and the poll webhook result endpoint returns it for 30 days, even if webhook delivery failed.
Reading the results
Match each result to the row you sent by its id, which is the record_id from the 202 response. Results can come back in any order, and a row that wasn't checked doesn't include the email address or phone number.
| Field | Meaning |
|---|---|
validation_status | validated when the validator confirmed that the email address accepts mail or that the phone number is valid and reachable. not_validated when it didn't confirm that. |
validator | The validator that answered, such as leadmagic or trestle. |
email or phone | The value that was checked. |
error | Present when the row wasn't checked. code and message explain why, for example credit_limit_exceeded when your credits ran out. |
data_sources | The validator step behind the result, including the validator's raw status and the credits it used. |
not_validated doesn't mean that the value is bad. It also covers a validator that couldn't reach a verdict, such as an email domain that accepts mail for any address. Say that the check didn't confirm the value rather than calling it invalid.
A row with neither validation_status nor error means the validator couldn't run the check, for example because the email address is malformed. That row costs 0 credits.
Phone numbers aren't format-checked before they're sent to the validator, so a malformed phone number is still checked, returns not_validated, and is charged. Send phone numbers in E.164 format, such as +12025550143.
The request-level status is success when processing finished. It doesn't mean every row was validated, so check total_failures and each row's validation_status or error.