# Phone Validation API
> Validate, parse and format phone numbers using Google libphonenumber: validity check, E.164 / national / international / RFC-3966 formats, country and calling code detection, and line type (mobile, fixed-line, VoIP, toll-free, premium-rate). Covers every country.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/phone-api/..."
```

## Pricing
- **Free** (Free) — 1,000 calls/Mo, 2 req/s
- **Basic** ($12/Mo) — 25,000 calls/Mo, 10 req/s
- **Pro** ($39/Mo) — 150,000 calls/Mo, 25 req/s
- **Mega** ($99/Mo) — 600,000 calls/Mo, 50 req/s

## Endpoints

### Validation

#### `GET /v1/example` — Example valid number for a country

**Parameters:**
- `country` (query, required, string) — 2-letter ISO country code Example: `US`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/phone-api/v1/example?country=US"
```

**Response:**
```json
{
    "data": {
        "e164": "+12015550123",
        "valid": true,
        "country": "US",
        "rfc3966": "tel:+12015550123",
        "possible": true,
        "line_type": "FIXED_LINE_OR_MOBILE",
        "country_name": "United States",
        "national_format": "(201) 555-0123",
        "national_number": "2015550123",
        "country_calling_code": "+1",
        "international_format": "+1 201 555 0123"
    },
    "meta": {
        "timestamp": "2026-05-29T22:25:38.904Z",
        "request_id": "982ea34a-52cc-4cba-8bc7-244a360dd51a"
    },
    "status": "ok",
    "message": "Example number retrieved successfully",
    "success": true
}
```

#### `GET /v1/verify` — Validate + parse a phone number

**Parameters:**
- `phone` (query, required, string) — E.164 (+14155552671) or national number Example: `+14155552671`
- `country` (query, optional, string) — 2-letter ISO country for national numbers Example: `US`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/phone-api/v1/verify?phone=%2B14155552671&country=US"
```

**Response:**
```json
{
    "data": {
        "e164": "+14155552671",
        "input": "+14155552671",
        "valid": true,
        "country": "US",
        "rfc3966": "tel:+14155552671",
        "possible": true,
        "line_type": "FIXED_LINE_OR_MOBILE",
        "country_name": "United States",
        "national_format": "(415) 555-2671",
        "national_number": "4155552671",
        "country_calling_code": "+1",
        "international_format": "+1 415 555 2671"
    },
    "meta": {
        "timestamp": "2026-05-29T22:25:38.959Z",
        "request_id": "615c3a48-5ba0-4829-bb7a-e22940f47063"
    },
    "status": "ok",
    "message": "Phone number verified successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/phone-api
OpenAPI spec: https://www.oanor.com/api/phone-api/openapi.json