> ## 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

> Valide números de telefone e obtenha informações sobre operadora, tipo de linha e país.

## Endpoint

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

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Valide qualquer número de telefone e obtenha metadados estruturados incluindo país, operadora, tipo de linha e saída formatada em E.164. A API de Validação de Telefone da Bunny normaliza entradas brutas em dados legíveis por máquina, ajudando a reduzir fraudes, melhorar a entregabilidade e controlar fluxos de SMS com números reais.

## Casos de uso

* Validar números de telefone no cadastro para reduzir contas falsas
* Detectar linhas VoIP ou pré-pagas antes de enviar SMS
* Normalizar números internacionais para o formato E.164
* Rotear chamadas ou mensagens com base na operadora ou região

## Detalhes

Aceita números em qualquer formato local ou internacional. O campo opcional `country` (ISO 3166-1 alpha-2, ex.: `BR`, `US`) melhora a precisão ao interpretar números locais sem código de país.

## Corpo da requisição

| Campo     | Tipo   | Obrigatório | Descrição                                                     |
| --------- | ------ | ----------- | ------------------------------------------------------------- |
| `phone`   | string | Sim         | Número de telefone a validar (qualquer formato)               |
| `country` | string | Não         | Código de país ISO 3166-1 alpha-2 como dica (ex.: `US`, `BR`) |

### Exemplo

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

## Resposta

### 200 OK

| Campo       | Tipo    | Descrição                                                           |
| ----------- | ------- | ------------------------------------------------------------------- |
| `valid`     | boolean | Se o número é válido                                                |
| `e164`      | string  | Número formatado em E.164                                           |
| `country`   | string  | Código de país ISO                                                  |
| `carrier`   | string  | Nome da operadora (quando disponível)                               |
| `line_type` | string  | Tipo de linha: `mobile`, `landline`, `voip`, `toll_free`, `unknown` |

**Exemplo**

```json theme={null}
{
  "valid": true,
  "e164": "+14155552671",
  "country": "US",
  "carrier": "AT&T",
  "line_type": "mobile"
}
```

### 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."
}
```

## Exemplo cURL

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