# Phone Number Format Guide 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](https://developers.mobile-text-alerts.com/getting-started/add-a-subscriber#example-response) 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 `+18002223333` 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":"+18002223333"` . 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](https://countrycode.org/), 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: `(800)222-3333` or `800-222-3333` becomes `+18002223333` in E.164. * International: `+447911123456` (UK), `+61412345678` (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](https://developers.mobile-text-alerts.com/getting-started/add-a-subscriber "mention") to learn more about the steps to creating subscribers with the API. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.mobile-text-alerts.com/tutorials/phone-number-format-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.