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-4567
  • 1-555-123-4567
  • (555) 123-4567
  • 555.123.4567
  • 1 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 None
function 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
end
static 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:

strictValidationBehaviorUse 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.
falseSends 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


Did this page help you?