Phone Number Format Guide

Learn how to format phone numbers in E.164 for subscriber creation to avoid confusion with country codes and leading digits.

When creating a new subscriber the phone number is the most critical field of the request. It provides more than a unique identifier but also the delivery address for every message sent to that subscriber. Also, if a phone number is supplied that already belongs to an existing subscriber, this will trigger an update of that subscriber rather than create a duplicate.

A correctly formatted phone number matters beyond just avoiding a 400 Bad Request error. Our API response for subscriber creation includes an e164Number field — the standardized international format — separately from the raw number you submitted. This is the system normalizing numbers internally.

It is important to have a clear strategy for handling phone number formatting before sending new subscriber requests to the API. Submitting numbers in one format helps prevent duplicate subscriber records.

Recommended format: E.164

E.164 is the international standard for formatting phone numbers, defined by the International Telecommunication Union (ITU). The name refers to the ITU-T recommendation number that specifies the format. E.164 formatting is recognized by carriers and routing systems worldwide as unambiguous. A number like 8002223333 could theoretically belong to multiple countries, while [phone] cannot. It uniquely identifies one phone line on the global network, which is exactly what a messaging system needs to route a message to the correct destination.

So while the number field can be submitted as a number/integer type it is recommended to format the phone number as a string in E.164 format to remove any confusion about the country codes and leading numbers.

You can also explicitly include the e164Number field in your request which takes precedence over number when supplied. This is the safest way to store international numbers.

Example: If you create a subscriber with "number": 18002223333 this would be stored as: "number":8002223333,"e164Number":"[phone]" . This may or may not be your desired result depending on the country code.

E.164 numbering plan format

A number in E.164 format has three components, written together as a single string with no spaces, dashes, or parentheses.

E.164 Format: +[country code][subscriber number]

Note: E.164 numbers can contain up to 15 digits, including the country code. A typical US number is 11 digits (12 characters with the leading +).

1. A + prefix, which distinguishes a string-format number from an integer. The + is literal, not a placeholder. This must be included as part of the format, with the string starting with the + character.

2. The country code, which varies in length from 1–3 digits. For example, US and Canada use one digit (1), the UK uses two digits (44), while some countries use three-digit codes ( 354 for Iceland). This means you cannot assume a fixed offset from the start of the number to where the local digits begin.

3. The subscriber number (the national number).

Examples of E.164 formatted numbers:

• US number: [phone] or 800-222-3333 becomes [phone] in E.164.

• International: [phone] (UK), [phone] (AU)

Common number format errors

• Numbers with a leading 0 when sent as an number will have all leading 0 digits removed. These numbers should be passed as a string in the number field or use the e164Number field.

• Omitting the country code and assuming it is a US/CAN number

• Mixing integer and string data types in the same subscribers array

• subscriberIds are not phone numbers, these are internal identifiers

See Add a Subscriber to learn more about the steps to creating subscribers with the API.