Phone number formatting
Which phone number formats the API accepts, and which to use.
The API accepts US and Canadian numbers in most common formats. For anything you store, look up, or compare, use one canonical form:
Preferred: 11 digits, country code first, digits only. For example, 15551234567.
What's accepted
US or Canada numbers only.
Preferred: 15551234567, 11 digits with the country code first and nothing else. Use this form for anything you store or compare.
Also accepted: these formats work for the same number:
5551234567+15551234567+1 (555) 123-45671-555-123-4567(555) 123-4567555.123.45671 555 123 4567
If you need to use one of these instead of the preferred format, test it with your own integration first.
Anything else, such as too few or too many digits, is rejected with 400 Invalid phone number(s).
Store numbers in the same 11-digit form the API returns. Contacts are looked up by phone number (GET /v1/contacts/{phoneNumber}), and reports and webhooks return 11 digits, so normalize numbers when they come in:
import re
def normalize(raw: str) -> str | None:
digits = re.sub(r"\D", "", raw)
if len(digits) == 10:
digits = "1" + digits
return digits if len(digits) == 11 and digits[0] == "1" else Nonefunction normalize(raw) {
let digits = raw.replace(/\D/g, "");
if (digits.length === 10) digits = "1" + digits;
return digits.length === 11 && digits[0] === "1" ? digits : null;
}<?php
function normalize(string $raw): ?string {
$digits = preg_replace('/\D/', '', $raw);
if (strlen($digits) === 10) $digits = '1' . $digits;
return (strlen($digits) === 11 && $digits[0] === '1') ? $digits : null;
}def normalize(raw)
digits = raw.gsub(/\D/, "")
digits = "1#{digits}" if digits.length == 10
digits.length == 11 && digits.start_with?("1") ? digits : nil
endstatic String normalize(String raw) {
String digits = raw.replaceAll("\\D", "");
if (digits.length() == 10) digits = "1" + digits;
return (digits.length() == 11 && digits.charAt(0) == '1') ? digits : null;
}static string? Normalize(string raw)
{
var digits = new string(raw.Where(char.IsDigit).ToArray());
if (digits.Length == 10) digits = "1" + digits;
return digits.Length == 11 && digits[0] == '1' ? digits : null;
}func normalize(raw string) (string, bool) {
digits := strings.Map(func(r rune) rune {
if unicode.IsDigit(r) {
return r
}
return -1
}, raw)
if len(digits) == 10 {
digits = "1" + digits
}
return digits, len(digits) == 11 && digits[0] == '1'
}If you already use libphonenumber or a port, parse with region US, format as E.164, and drop the +.
Using strict validation
When a number in toNumbers can't be parsed, strictValidation decides what POST /v1/messages does:
strictValidation | Behavior | Use when |
|---|---|---|
true (default) | If any number is invalid, sends to nobody and returns 400. | Most sends: a bad number is an error you can act on, not a silent skip. |
false | Sends to every valid number, skips the invalid ones, returns 201. | Bulk sends: one bad row shouldn't stop ten thousand good ones. |
What formatting can't tell you
A number in a valid format can still be unable to receive texts: most landlines, some VoIP numbers, and disconnected numbers. Those show up in the delivery report afterwards as bounced, not in the response to your send. If it matters, read GET /v1/message-reports/{id}/responses/delivery with filters[status][eq]=bounced. A number that has opted out is different: a send to it is rejected with a 400, "The phone numbers that you're sending to are opted out". Check optOut on the contact before you send.
Related
- Core concepts — contacts, groups, and how phone numbers identify them
- Errors — what a
400response tells you - Send, track & receive — checking the delivery report
- Troubleshooting
Try Troubleshooting, check status.eztexting.com, or contact support.
Updated about 18 hours ago