Contact Data Validation API - Email, Phone, Address, Lead

Eighteen validation and enrichment services behind one key, over one records list. Score a lead, verify an address, look up the name on a phone line, or standardise a hundred thousand addresses. One flat row per record.

What this actor does

• Scores a lead and cross-checks its parts. Most validation tools judge the email, the phone and the address in isolation and hand you three verdicts. This one also checks them against each other, so a real phone number registered three states away from the address on the form comes back as a problem rather than as three passes. Every component score is lifted onto the row alongside the overall score, because the disagreement is usually the finding.
• Runs eighteen services from one list. Every mode reads the same records list and takes different fields out of it, so one prepared list of contacts can go through lead scoring, then email validation, then address standardisation, without being rewritten between passes.
• Verifies email deliverability and repairs typos. Returns the deliverability verdict with separate flags for catch-all domains, disposable providers, role accounts, spam traps, expired domains and vulgar addresses, plus the corrected address when the input was an obvious misspelling.
• Looks up who is on a phone line. Line type, carrier, city, state and time zone, and at full depth the name and address of the contact the number belongs to. Two append modes work the other way, finding the number from a person at an address or from a business.
• Standardises addresses in the United States and worldwide. Delivery point validation, residential and business classification, carrier route, county, congressional district and the parsed fragments of the address. The international service covers the rest of the world in the local format.
• Recovers an address from partial details. The detective modes take what a form actually collected - a street and a name, a wrong city, a postal code that does not match - and work out the real address rather than failing the record.
• Geocodes forwards and backwards. Turn an address into coordinates and place data, or coordinates into the places around them, with a search radius you control.
• Parses and judges names. Splits a name into title, first, middle, last and suffix, returns a gender, and flags bogus entries, vulgar entries and celebrity names, which are what a public form collects when it is being tested or abused.
• Tells three kinds of failure apart. This provider reports every failure inside a normal response body, so the status line says nothing. A rejected key stops the run because it will never fix itself, a rejected record is written as a miss and the run continues, and a service level failure fails over to the backup host the provider publishes for exactly that case.
• Distinguishes a wrong key from an unlicensed service. Each service is licensed separately here, so a perfectly valid key can be refused by a service that is not on your plan. That is a subscription question, not a typo, and the actor says which one it is.
• Never charges for a miss. Only rows carrying a resolved result are billed.

Input

Field	What it does
mode	Which of the eighteen services to call.
records	The records to validate, one JSON object per line.
emails	Shorthand for the email mode: addresses one per line.
phones	Shorthand for the phone mode: numbers one per line.
names	Shorthand for the name mode: names one per line.
addresses	Shorthand for single-line address and geocode modes.
testType	Judge leads as business or consumer, with or without an address.
phoneTestType	How deep the phone lookup goes.
nameOption	The option string passed to the name service.
allowEmailCorrections	Repair an obvious email typo before validating.
emailTimeoutMs	Milliseconds the email service may spend on the mail server.
maxMatchesPerRecord	How many geocoding results one record may return.
searchType	Search type passed to the geocoding modes.
minCertainty	Keep only leads at or above this score.
leadQualities	Keep only leads with these quality ratings.
requireDeliverableEmail	Drop rows whose email component is unusable.
requireValidPhone	Drop rows whose phone component is unusable.
requireValidAddress	Drop rows whose address component is unusable.
environment	Production, with failover, or the trial host.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave misses and rejected records out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own license key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "lead-validation",
  "query": "Jane Doe | jane.doe@example.com | 8055551234 | 27 E Cota St, Santa Barbara, CA, 93101",
  "overallCertainty": 87,
  "overallQuality": "Pass",
  "leadType": "Business",
  "leadCountry": "US",
  "noteCodes": "3,7",
  "noteDescription": "Phone is a mobile line, Email domain is a business domain",
  "nameCertainty": 95,
  "nameQuality": "Pass",
  "firstName": "Jane",
  "lastName": "Doe",
  "addressCertainty": 92,
  "addressQuality": "Pass",
  "addressLine1": "27 E COTA ST",
  "addressCity": "SANTA BARBARA",
  "addressState": "CA",
  "addressPostalCode": "93101",
  "addressIsValid": true,
  "emailCertainty": 88,
  "emailQuality": "Pass",
  "emailCorrected": "jane.doe@example.com",
  "emailIsDeliverable": true,
  "phoneCertainty": 76,
  "phoneQuality": "Review",
  "phoneCity": "Santa Barbara",
  "phoneState": "CA",
  "phoneIsValid": true,
  "phoneContactName": "JANE DOE",
  "phoneContactType": "Wireless",
  "businessCertainty": null,
  "error": null,
  "raw": { }
}

Frequently asked questions

What does lead validation actually do that separate checks do not?

It cross-references. Validating an email, a phone number and an address separately gives you three independent verdicts, and a fabricated lead can pass all three by combining real components that have nothing to do with each other. This service checks whether the name, address, phone, email and IP address are consistent with one another, and scores both the lead as a whole and each component on a zero to one hundred scale, with note codes explaining what it found. The overall quality is expressed as pass, review or fail, so a form can route the review cases to a human instead of discarding them.

How do I decide between the business and consumer test types?

Pick the one the lead is. A business lead is judged against business listings and company data, a consumer lead against consumer records, and a lead judged against the wrong set will score badly for no real reason. The two no-address variants are for forms that never collected an address at all, and they exist so that a missing field does not drag the overall score down as though it were a wrong field.

What does the phone lookup return?

At basic depth, the line type and the carrier. At business depth, business listing data attached to the number. At full depth, the contact behind the line: name, address, city, state and whether the line is wireless, landline or VoIP. That last one is the difference between knowing a number is dialable and knowing who picks it up. Deeper lookups spend more of your provider credits, so the depth is a run setting rather than a fixed choice.

What is address detective for?

For the records a plain validator gives up on. Real forms collect a street with no city, a city with the wrong postal code, or a name and a phone number with a half-typed address. The detective modes take those partial details and work out the real address, and the outlying variant handles the case where the city or postal code supplied is simply wrong rather than missing. Running validation first and the detective on the failures is usually cheaper than losing the records.

What is the difference between a wrong key and an unlicensed service?

Each service here is licensed separately, so your key can be entirely valid and still be refused by a service you have not subscribed to. Those two failures look nearly identical in the raw response, and confusing them sends you hunting for a typo that does not exist. The actor reports them separately: one says the key was rejected, the other says the key was accepted but the service is not on your plan.

Why does the actor need to know about a backup host?

Because this provider publishes one, and it is the documented answer to a service level failure rather than an exotic fallback. Failures here arrive with a normal HTTP status and an error object in the body, and one of the error types means the service itself is in trouble. On that error the actor retries the request against the backup host instead of failing the record, which is what keeps a long run alive through a brief outage. This applies to the production environment; a trial key runs against the trial host, which has no backup.

Can I run the same list through several modes?

Yes, and that is what the shared records list is for. Every mode reads the same objects and simply takes different fields out of them, so a list carrying names, emails, phones and addresses can be scored as leads, then validated for email, then standardised for address, without being reshaped in between. Each run is a separate run and is billed separately.

Which fields does a record need?

Only the ones the mode uses. Lead scoring makes use of everything you give it and scores what is missing as unknown rather than failing. Email validation needs email, phone lookup needs phone, name validation needs fullName, city and postal code validation needs postalCode, and reverse geocoding needs latitude and longitude; records missing the field their mode requires are dropped before the request rather than sent and charged for. Everything else is optional and improves the answer.

Do I need my own API key?

Yes. This actor does not include data access. You use your own license key from Service Objects, which is the provider whose contact validation API this actor calls, obtained from their site. Your own plan, credit balance and terms apply. Paste the key into the apiKey field, where it is stored as an Apify secret. Set environment to trial if your key was issued for the trial host, since a key issued for one host does not work on the other.

What happens when a record returns nothing?

An undeliverable address or a failing lead is a verdict, not a miss: the provider telling you the record is bad is the question you asked, so that row is written and billed like any other. A miss is a record the provider returned no result for at all, and a rejection is a record it refused as malformed. Both are written with found: false and never billed, and the rejection carries the provider's own explanation. Set skipNotFound to true to leave them out of the dataset entirely.

How much does a run cost?

Pricing is pay per result: you are charged for each record resolved into the dataset, and never for misses, for rejected records, for rows dropped by the filters, or for duplicates. Note that the geocoding modes can return several matches for one record and each match is a row. Apify platform usage is included in the per-result price. Your own API provider's credit balance is separate and billed by them.

Keyword map

contact validation API, lead validation API, lead scoring API, email validation API, email verification, phone validation API, phone append, reverse phone lookup, caller name lookup, line type detection, address validation API, US address validation, international address validation, address standardisation, delivery point validation, DPV, residential delivery indicator, address parsing, address autocomplete alternative, city state zip validation, secondary unit numbers, geocoding API, reverse geocoding, name validation API, name parsing, bogus name detection, form validation, lead form fraud, data quality API, data cleansing, CRM data hygiene