Use libphonenumber to parse what a user typed, check that it's a plausible number for a region and format it as E.164 (+12125550199) before you call an SMS API. It catches typos and missing country codes at your form. It can't tell you whether the line is live, a landline or willing to receive texts.
Bad numbers cost real money and cause real support tickets. A number with a stray digit gets refused or lands on a stranger. Cleaning input at the edge is the cheapest fix. We make Ready, which treats a 10-digit US number as +1, but your code shouldn't rely on that for international users. The format rules are in E.164 formatting for SMS APIs.
Parse, validate, format
In JavaScript with libphonenumber-js:
import { parsePhoneNumberFromString } from 'libphonenumber-js';
function toE164(input, defaultCountry = 'US') {
const n = parsePhoneNumberFromString(input, defaultCountry);
if (!n || !n.isValid()) return null;
return n.number; // "+12125550199"
} In Python with phonenumbers:
import phonenumbers
def to_e164(raw, region="US"):
try:
n = phonenumbers.parse(raw, region)
except phonenumbers.NumberParseException:
return None
if not phonenumbers.is_valid_number(n):
return None
return phonenumbers.format_number(n, phonenumbers.PhoneNumberFormat.E164) The default region matters. "2125550199" is a valid US number when the region is US and nothing useful when it isn't.
What the library tells you, and what it doesn't
| Question | libphonenumber | A live check |
|---|---|---|
| Is the format plausible for the region? | Yes | Yes |
| Does it follow the numbering plan? | Yes | Yes |
| Is the line assigned and active? | No | Yes |
| Is it mobile, landline or VoIP? | Sometimes, by range | Yes |
| Can it receive SMS today? | No | Partly |
The library works offline from number-range metadata, which gets stale. A number can pass validation and still be disconnected. For the second column, use a lookup. Ready has GET /v1/validate/:phone, covered in the number validation docs. Also see how to check whether a number can get texts.
Where to validate
- At the form. Show an error before the user leaves, with the country selector visible.
- On import. Normalize a whole CSV, count rejects and show them, never silently drop them.
- Before every send. Re-parse stored numbers if your metadata library has updated.
- Store both. Keep the raw input and the E.164 value, so you can recover from a bug.
Mistakes to avoid
- Stripping the leading
+and then guessing the country. - Treating "invalid" as "don't text." Show the user the problem instead of deleting the contact.
- Using a regex for validation. Numbering plans change, and a regex ages badly.
- Forgetting extensions. An office number with an extension can't receive a text anyway.
Cost of getting it wrong
A refused or wrong-number text still costs your time, and a text that goes out costs $0.0075 plus the $0.0045 carrier fee per segment. For a 5,000-row import with a 3% bad-number rate, that's 150 numbers to catch before sending. The figures are assumptions.
Frequently asked questions
Which package should I use? Google's libphonenumber and its ports (libphonenumber-js, phonenumbers, libphonenumber-csharp) share the same data.
Do I need it if Ready normalizes numbers? It's still better to catch errors at your form, where the user can fix them.
How often should I update it? With your normal dependency updates, since numbering plans change.
Next step
Add the function at your sign-up form and your CSV import, and log how many inputs it rejects in the first week.
Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.