# Phone Number Validator and Formatter
Validate, parse and format phone numbers from every country in a single request. The API tells you whether a number is valid, what kind of line it is, which country it belongs to, and returns it in all the formats you need for storage, display and dialing.
## What you get
- **Validation** — `valid` and `possible` flags plus a machine-readable `reason` for invalid input (`TOO_SHORT`, `TOO_LONG`, `INVALID_COUNTRY`, `NOT_A_NUMBER`, ...).
- **Line type detection** — `MOBILE`, `FIXED_LINE`, `FIXED_LINE_OR_MOBILE`, `TOLL_FREE`, `PREMIUM_RATE`, `VOIP`, `PAGER`, `UAN`, `VOICEMAIL` and more.
- **Country detection** — ISO 3166-1 alpha-2 region and the country calling code.
- **Four output formats** — E.164 (`+4915123456789`), international (`+49 1512 3456789`), national (`01512 3456789`) and RFC 3966 (`tel:+4915123456789`).
- **Batch validation** — up to 100 numbers per request, results returned in the same order.
- **Helpers** — example numbers per country and line type, calling-code lookup, and the full list of supported regions.
## Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | `/validate?number=+4915123456789&country=DE` | Validate and format one number |
| POST | `/validate/batch` | Validate up to 100 numbers |
| GET | `/example?country=DE&type=mobile` | Example number for a region |
| GET | `/calling-code?country=DE` | Country calling code |
| GET | `/regions` | All supported regions and calling codes |
Numbers can be passed in E.164 form (with a leading `+`) or in national form together with a `country` hint.
## Example
Request:
```
GET /validate?number=%2B4915123456789
```
Response:
```json
{
"input": "+4915123456789",
"valid": true,
"possible": true,
"type": "MOBILE",
"country": "DE",
"countryCallingCode": "49",
"formats": {
"e164": "+4915123456789",
"international": "+49 1512 3456789",
"national": "01512 3456789",
"rfc3966": "tel:+4915123456789"
}
}
```
Invalid numbers still return HTTP 200 with `valid: false` and a `reason`, so a single code path handles every input. Only malformed requests (missing parameter, batch over 100 items, bad JSON) return 4xx.
## Typical use cases
- Clean up sign-up and checkout forms before storing a number.
- Normalise CRM or marketing lists to E.164 before sending SMS or placing calls.
- Detect mobile vs. fixed-line numbers to pick the right contact channel.
- Display numbers in the caller's local convention.
- Deduplicate contact databases that mix national and international formats.
## How it works
Validation is ruleset-based and runs on a globally distributed edge network, so responses are fast from anywhere in the world. Numbering-plan metadata comes from Google's libphonenumber project (the same rules used by Android) and is updated regularly.
This API does **not** perform live carrier, HLR or number-portability lookups and does not guarantee that a number is currently in service or reachable. It tells you whether a number is well-formed and assigned under the national numbering plan.
## Coverage
All 240+ regions with an ITU-assigned calling code are supported. Use `/regions` to retrieve the current list.