"Validate this phone number" can mean three different things, and each one catches problems the one before it can't.
This guide goes through them in order: is the number correctly formed, is the line real and in use, and does it reach the person you're about to call.
The three levels
| Level | What it checks | What it misses |
|---|---|---|
| Format | What it checks: The number is correctly formed for its country | What it misses: Whether it's in service |
| Line | What it checks: The number is real, its line type and whether it's active | What it misses: Who it belongs to |
| Person | What it checks: The number belongs to the contact and is worth a call | What it misses: Whether you may call it, which is a separate question |
Level 1: check the format
A format check confirms a number has the right length and structure for its country. For US numbers that means the North American Numbering Plan: a three-digit area code, a three-digit exchange and four digits.
It's free and instant, and it should run everywhere a number enters your system. It's also the only level you can do without a data source.
A plus sign, the country code and the number, with no spaces. It's the one format every CRM, dialer and API agrees on.
Level 2: check the line
A correctly formed number can still be disconnected, unassigned or a type of line nobody answers. Checking the line needs a live data source.
The useful facts at this level are whether the number is valid, what kind of line it is (mobile, landline or VoIP), and whether the line shows signs of recent use.
A format library can't give you the line type for US numbers. libphonenumber reports most of them as "fixed line or mobile", because a number can move between carriers and line types. That is the gap a live check fills.
Level 3: check the person
A live mobile that now belongs to somebody else is a wrong-number call. The last check is whether the number belongs to the name on your list.
Put that together with the line checks and you can answer the question the list is really for: is this contact worth a call?
Doing levels 2 and 3 in one call
What comes back
Each contact gets one answer. will_this_person_answer is high_chance, low_chance or bad_data, and action says what to do with the contact: phone, multi_channel or email_linkedin. You route on those two fields and ignore the raw line data. The full response has a few more fields, listed in the API reference.
Common mistakes
- Stopping at the format check. A well-formed number can still be disconnected or belong to somebody else.
- Checking a list once and dialing it for months. Numbers are reassigned and disconnected all the time.
- Storing numbers with spaces, brackets and dashes. Keep the E.164 form and format only for display.
- Treating a valid number as permission to call it.
Putting it into practice
- 1
Format-check on entry
Reject or fix malformed numbers when they're typed or imported.
- 2
Check before you dial
Run the line and person checks close to the calling session, not once a year.
- 3
Route on the answer
Dial High chance and Low chance; send Bad data to email and LinkedIn.
A valid, reachable number doesn't settle whether you may call it. Check the rules that apply to your calls separately.