Phone validation
Check whether a phone number is real and reachable right now, and see its carrier, line status, and caller ID name.
Phone validation
Phone validation tells you whether a number is real and reachable right now before you dial it or send it to a sales team. Send one number; we check it live and return a status you can act on, plus the carrier, porting and roaming status, and the caller ID name on the line.
Use it on numbers you already have: a CRM backfill, inbound form fills, or phones from another provider, or to re-check a number from Contact Reveal before a call campaign.
What comes back
| Field | What it tells you |
|---|---|
validationStatus | The verdict: valid_reachable, valid_not_reachable, invalid, or unknown |
validationScore | The same verdict as a number: 10 valid and reachable, 6 valid but not reachable, 2 unknown, 0 invalid |
isValid | Whether the number exists at all |
isReachable | Live line status: reachable, not_reachable, bad_number, or unknown |
isPorted, isRoaming | Whether the number moved to another carrier, and whether it's roaming now |
currentCarrier, originalCarrier | Who serves the number today and who issued it |
callerIdName | The name that shows up on caller ID, when the carrier exposes one |
formattedNumber, nationalFormat, countryIsoCode, countryName, countryCallingCode | The number normalized, with its country |
How to read it:
valid_reachable: dial it.valid_not_reachable: the number exists but the line is off or out of service right now. Try again later, or don't prioritize it.invalid: the number doesn't exist. Remove it.unknown: the network didn't give a clear answer. Treat it as unverified.
callerIdName is a quick way to confirm a number belongs to the person you
think it does.
Inputs
Send the number in E.164 (+14155551234) for the most reliable result. Spaces,
dashes, and parentheses are accepted too. A number we can't parse returns
400 with a hint to use E.164.
patience sets how long we wait for the live network check:
patience | Wait |
|---|---|
MINIMUM | About 5 seconds |
LOW | 15 seconds |
MEDIUM | 30 seconds |
HIGH (default) | 60 seconds |
EXTREME | 2 minutes |
MAXIMUM | 10 minutes |
Longer waits catch slow networks and return fewer unknown results. Set your
client timeout above the patience you choose: at least 60 seconds for the
default.
{
"apiKey": "sk_live_...",
"phoneNumber": "+14155551234",
"patience": "HIGH"
}Operations
| Operation | What it does | Reference |
|---|---|---|
| Phone validation | Check one phone number live | validatePhoneNumber |
The endpoint allows 60 requests per minute. For a list of numbers, run requests in parallel within that limit.
Using it effectively
- Validate before you dial at scale. A quick pass over a list removes dead numbers before your team spends time on them.
- Re-check old numbers. A number that was reachable last year may not be today; validate before a new campaign.
- Use the score for sorting. Order a call list by
validationScoreso reachable numbers come first.
Credits
3 credits per number checked, including numbers that turn out to be invalid: the check itself is the product. Requests that fail before the check runs (a malformed number, an error on our side) aren't charged. See Billing & credits.
Credit amounts are defaults — custom pricing is available for bulk use cases.
Related: Email validation · Contact Reveal · Reverse phone lookup