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

# POST /phone-validation

> Validate phone numbers and retrieve country, calling code, and E.164 formatting information.

## Endpoint

```
POST https://api.bunny.build/api/v1/phone-validation
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Validate any phone number and retrieve structured metadata including country, calling code, and E.164 formatted output. The API normalizes the input number and identifies its country and national subscriber number, helping you reduce fraud, improve deliverability, and gate SMS flows on correctly formatted numbers.

## Use cases

* Validate phone numbers at sign-up to reduce fake accounts
* Normalize international numbers to E.164 format
* Identify the country and calling code for routing logic
* Gate SMS flows on properly formatted phone numbers

## Details

Accepts numbers in E.164 format (e.g. `+14155552671`). The number must include a leading `+` and country calling code. Spaces, dashes, dots, and parentheses are stripped automatically before parsing.

## Request body

| Field   | Type   | Required | Description                                                  |
| ------- | ------ | -------- | ------------------------------------------------------------ |
| `phone` | string | Yes      | Phone number to validate (E.164 format, e.g. `+14155552671`) |

### Example

```json theme={null}
{
  "phone": "+14155552671"
}
```

## Response

### 200 OK

| Field             | Type    | Description                                               |
| ----------------- | ------- | --------------------------------------------------------- |
| `phone`           | string  | Original phone number as submitted                        |
| `valid`           | boolean | Whether the number is valid                               |
| `e164`            | string  | E.164 formatted number                                    |
| `country_code`    | string  | ISO 3166-1 alpha-2 country code (e.g. `"US"`)             |
| `calling_code`    | string  | International calling code with leading `+` (e.g. `"+1"`) |
| `national_number` | string  | Subscriber number without the calling code                |

**Example**

```json theme={null}
{
  "phone": "+14155552671",
  "valid": true,
  "e164": "+14155552671",
  "country_code": "US",
  "calling_code": "+1",
  "national_number": "4155552671"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Invalid or unparseable phone number"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/phone-validation \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+14155552671"}'
```