> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Number Format

> Which phone number formats telli accepts, how numbers are normalized, and why everything is stored in E.164

telli stores phone numbers in **[E.164](https://en.wikipedia.org/wiki/E.164)**, the international standard format: a `+`, the country code, and the subscriber number, with no spaces, punctuation, or national dialing prefix - for example `+4915112345678` or `+14155552671`. Numbers that pass validation are normalized to this form and returned that way in API responses, webhook payloads, and exports.

You don't have to submit numbers in exact E.164, though. Every path that brings contacts into telli - the contact API, CSV import, and the CRM integrations - runs numbers through the same normalization and validation, then stores the E.164 result.

## Accepted input formats

Using a German mobile number as an example, these inputs all normalize to `+491751234567`:

| Input              | Accepted | Notes                                                            |
| ------------------ | -------- | ---------------------------------------------------------------- |
| `+491751234567`    | ✅        | Already E.164                                                    |
| `+49 175 1234567`  | ✅        | Spaces, dots, hyphens, and parentheses are ignored               |
| `0049 175 1234567` | ✅        | The `00` international prefix is converted to `+`                |
| `491751234567`     | ✅        | A missing `+` is added when the digits start with a country code |
| `+491751234567`    | ✅        | Leading and trailing whitespace is trimmed                       |
| `01751234567`      | ❌        | National format without a country code - see below               |

After normalization, telli validates the number against the numbering plan of the detected country and rejects numbers that aren't valid there, such as an unrecognized country code or an impossible length.

## Why national formats are rejected

A number like `01751234567` is ambiguous: without a country code, telli can't tell whether it's a German, Austrian, or other number. Guessing a default country would silently turn some numbers into valid-looking but wrong international numbers - and calls would reach the wrong person. That's why numbers must carry explicit country context.

Convert national numbers to E.164 on your side before sending them. For German numbers that's a simple transformation: replace the leading `0` with `+49` (`01751234567` → `+491751234567`). The rule differs by country - Italian numbers keep their leading zero after `+39`, for example - so for anything beyond a single known country, use a library instead of a hand-rolled rule.

<Tip>
  If you integrate in code, use a [libphonenumber](https://github.com/google/libphonenumber) port for your language to parse and format numbers to E.164 - ports exist for JavaScript, Python, Java, PHP, and most other ecosystems.
</Tip>

## Where this applies

The same normalization and validation runs on the main paths where phone numbers enter telli:

* The contact API - [v2](/v2/endpoint/create-contact) and [v1](/v1/endpoint/add-contact)
* [CSV import](/platform/contacts#csv-import) in the app
* The [HubSpot](/integrations/hubspot) and [Salesforce](/integrations/salesforce) CRM integrations

Numbers accepted on these paths are stored - and later returned in [webhook payloads](/webhooks), API responses, and exports - as the normalized E.164 number.

### Fields that require strict E.164

A few fields skip the lenient normalization and only accept numbers that already start with `+`. The `00` prefix and bare country-code forms are rejected there:

* Values of custom [contact properties](/platform/contact-properties) with the `phone_number` type (spaces and punctuation are tolerated)
* An agent's [transfer number](/deep-dives/call-transfer) (digits only - no spaces or punctuation)