Contact Verification API - Email, Phone and Address

Check a whole contact record at once rather than three separate services. Send the email address, the phone number and the postal address together, get a verdict on each, and get the postal address back standardised and corrected. One flat row per contact.

What this actor does

• Verifies three things in one call. Email, phone and postal address are sent as a single contact record and each comes back with its own verdict and its own detail code. That distinction is the point: a lead with a good address and a dead phone is a different problem from one with a good phone and a mistyped street, and a single overall verdict hides which it is.
• Returns the corrected postal address. The provider standardises and corrects the address it was given, and returns the corrected form plus the county. A street written as "4010 Boy Scout Boulevard, Suite 1100" comes back in the postal service's own spelling with the full plus four postcode. A addressCorrected flag says whether it had to change anything.
• Gives the detail behind the verdict. Eleven documented detail codes sit under a non-valid email verdict, separating a mailbox that does not exist from a mailbox that is full, a disposable provider from a role address, and a temporary error that will pass on a retry from a permanent block. All eleven are offered as a filter.
• Runs real time or bulk, whichever fits. Real time verifies one contact per request and answers immediately, which suits a few hundred records. Bulk creates a list on the provider's side, polls its own reported state and walks its own reported page count, which suits tens of thousands. Neither state nor page count is guessed at, so a list that finishes faster or slower than expected still exports correctly.
• Handles both kinds of API key. This provider issues server side and client side keys, and each answers on its own path; the wrong pairing is rejected without a useful explanation. The actor defaults to the server side path and exposes the other as an option, and says so in the error message when a key is refused.
• Pairs your three lists line by line. Emails, phones and postal addresses are matched by position into one contact each, so line three of one list belongs to the same person as line three of the others. Any one list on its own is a valid run.
• Counts an invalid contact as a result, not a miss. The provider answers HTTP 200 with a status of invalid, which is exactly the question being asked. Only a record with no verdict at all is a miss, and misses are never billed.

Input

Field	What it does
mode	Real time, or bulk lists.
emails	Email addresses to verify.
phones	Phone numbers, paired line by line with the emails.
postalAddresses	Postal addresses, paired line by line with the rest.
keyType	Whether your key was generated server side or client side.
emailStatuses	Keep only these email verdicts.
phoneStatuses	Keep only these phone verdicts.
addressStatuses	Keep only these address verdicts.
statusDetails	Keep only these email detail codes.
excludeRoleAddresses	Drop shared inboxes such as info and support.
excludeDisposable	Drop throwaway addresses.
requireAllValid	Keep only contacts where every submitted part is valid.
listSize	Contacts per bulk list.
requestsPerMinute	Pace the run under your plan's rate limit.
skipNotFound	Leave contacts with no verdict out of the dataset.
maxResults	Hard cap on rows, and therefore on spend and run time.
apiKey	Your own API key. Stored as a secret.

Example output

{
  "found": true,
  "mode": "verify",
  "query": "jane.doe@example.com | 18009618205 | 4010 Boy Scout Boulevard, Suite 1100, Tampa, FL, 33607",
  "contactId": "row_1",
  "email": "jane.doe@example.com",
  "emailStatus": "valid",
  "emailStatusDetail": null,
  "emailAccount": "jane.doe",
  "emailDomain": "example.com",
  "emailConnected": null,
  "phone": "18009618205",
  "phoneStatus": "valid",
  "phoneServiceType": "land",
  "phoneLocation": null,
  "address1": "4010 W Boy Scout Blvd Ste 1100",
  "address2": " ",
  "city": "Tampa",
  "state": "FL",
  "zip": "33607-5796",
  "county": "Hillsborough",
  "addressStatus": "valid",
  "addressCorrected": true,
  "durationSeconds": 0.392828819,
  "error": null,
  "raw": { }
}

Frequently asked questions

What does verifying a whole contact record mean?

It means one request carries the email address, the phone number and the postal address for the same person, and the answer carries a verdict for each. You get back whether the mailbox exists, whether the number is a real reachable line and what kind of line it is, and whether the postal address is deliverable, along with the corrected form of that address. Verifying the three separately with three services gives you the same facts but no way to see the record as a whole, which is what you actually act on.

What is the difference between the verdict and the detail code?

The verdict is one of valid, invalid, accept all, risky or unknown. The detail code is what sits underneath a verdict that is not valid, and it is where the decisions live. An invalid email can mean the format is wrong, the domain does not exist, or the domain is fine and the specific mailbox is not, and those call for three different follow ups. A risky verdict can mean a full mailbox, a disposable provider, a role address or a server that returned an uncertain answer. Filtering on the detail code is how you retry the recoverable ones and drop the rest.

Does it correct a postal address, or just judge it?

It corrects it. The provider returns the address standardised to the postal service's own formatting, with the full postcode and the county added, and a flag saying whether anything had to change. That is the practical reason to run an address check rather than a syntax check: a form entry that a human would read as correct is very often not the form the postal service will route on, and the corrected version is the one to store.

Real time or bulk, which should I use?

Real time for anything up to a few hundred contacts, or whenever you want the answer during the run. It verifies one record per request and returns the corrected address. Bulk for tens of thousands: it creates a list on the provider's side, and the run then spends most of its time waiting rather than requesting. Bulk trades immediacy for throughput, and the actor polls the provider's own reported progress rather than a fixed schedule, so a list that finishes early is exported early.

My API key is being rejected. Why?

Almost always because of the key type. This provider issues two kinds of key, one meant for browser code and one meant for server code, and each answers only on its own path. A server side key sent to the client side path is refused, and so is the reverse, with a message that does not say which mistake was made. Set the key type field to match the key you generated on the provider's dashboard. An actor is server side, so that is the default here.

Can I verify only phone numbers, or only addresses?

Yes. The three input lists are paired by position into one contact record each, and any list you leave empty is simply not part of the record. A run with only phone numbers verifies only phones. The actor also leaves the unused fields out of the request rather than sending empty strings, which matters because asking the provider to verify an empty value is a request you would still be charged for.

What counts as a miss, and what gets charged?

An invalid contact is a result, not a miss: the provider answering that a mailbox does not exist is exactly the question you asked, so that row is written and billed like any other. A miss is a record the provider returned no verdict for at all, and those are written with found: false and never billed. Rows dropped by your filters and duplicate rows are not billed either.

Do I need my own API key?

Yes. This actor does not include data access. You use your own API key from BriteVerify, which is the provider whose contact verification API this actor calls, created on their dashboard. Your own plan, credit balance and terms apply. Paste the key into the apiKey field, where it is stored as an Apify secret. The key travels in a request header rather than on the URL.

How does this handle rate limits and spent credits?

Requests are spaced evenly across the minute so a long list does not bunch up against the limiter, and the pace is yours to set. A rate limit or server error is retried with backoff, because it clears on its own. An empty credit balance is treated differently: the provider reports it with its own status code, the actor recognises it and stops with what it has rather than burning retries on a balance that waiting will not refill.

How much does a run cost?

Pricing is pay per result: you are charged for each contact record resolved into the dataset, and never for records with no verdict, for rows dropped by the filters, or for duplicates. 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 verification API, email verification API, phone validation API, address validation API, postal address standardisation, CASS address correction, real time verification, bulk verification, list cleaning, lead form validation, checkout address validation, role address detection, disposable email detection, mailbox full detection, catch-all detection, landline versus mobile, line type lookup, county append, data quality, CRM hygiene