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

# Quick Start

> Verifique e-mails, telefones e consulte CPF com a API v1 — síncrono (até 10) ou batch assíncrono.

<Tip>
  Do **cadastro limpo à primeira verificação** em poucos passos. E-mail usa **`validations:email`**; telefone usa **`validations:phone`**; CPF usa **`validations:cpf`**. A cobrança segue o modo ou SKU — [Modos e cobrança](/validations-api/como-funciona/modos-e-cobranca).
</Tip>

## Em poucas palavras

* **E-mail** — confere se o endereço existe antes de enviar campanha ou transacional.
* **Telefone** — confere formato e, no modo completo, se **tem WhatsApp**.
* **CPF** — modo **rápida** (formato) ou **completa** (base oficial do governo via parceria).
* **Até 10** na API síncrona ou painel; **lotes grandes** via batch assíncrono.

## Antes de começar

| Item             | E-mail                                             | Telefone            | CPF               |
| ---------------- | -------------------------------------------------- | ------------------- | ----------------- |
| Escopo na chave  | `validations:email`                                | `validations:phone` | `validations:cpf` |
| Créditos ou PAYG | Sim                                                | Sim                 | Sim               |
| Autenticação     | `Authorization: Bearer sk_live_...` ou `x-api-key` | Idem                | Idem              |

Base URL: `https://api.notifique.dev`.

***

## E-mail — verificação imediata (até 10)

Manda a lista e recebe o resultado na mesma resposta — ideal no cadastro ou antes de importar uma planilha pequena.

```http theme={null}
POST /v1/validations/email
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

**Modo rápida** — formato, domínio descartável e MX (mais barato):

```json theme={null}
{
  "emails": ["cliente@example.com", "bounce@dominio-invalido.xyz"],
  "mode": "quick"
}
```

**Modo completa** — inclui checagem de caixa de entrada (mais profunda):

```json theme={null}
{
  "emails": ["cliente@example.com"],
  "mode": "full"
}
```

Resposta **200**:

```json theme={null}
{
  "success": true,
  "data": {
    "mode": "quick",
    "total_credits_charged": 1,
    "results": [
      {
        "email": "cliente@example.com",
        "status": "valid",
        "reason": null,
        "disposable": false,
        "mx_found": true,
        "catch_all": false,
        "suggested_spelling": null,
        "credits_charged": 1
      },
      {
        "email": "bounce@dominio-invalido.xyz",
        "status": "invalid",
        "reason": "MX record not found",
        "disposable": false,
        "mx_found": false,
        "catch_all": null,
        "suggested_spelling": null,
        "credits_charged": 0
      }
    ]
  }
}
```

### E-mail — lote grande (até 10.000)

Para listas grandes, o processamento roda em background — você consulta o progresso depois.

```http theme={null}
POST /v1/validations/email/batch
```

```json theme={null}
{
  "emails": ["a@example.com", "b@example.com"],
  "mode": "full"
}
```

Resposta **200** (job enfileirado):

```json theme={null}
{
  "success": true,
  "data": {
    "job_id": "job_email_abc123",
    "status": "queued",
    "total": 2,
    "mode": "full"
  }
}
```

Consulte o progresso:

```http theme={null}
GET /v1/validations/email/batch/{jobId}
```

***

## Telefone — verificação imediata (até 10)

Mesma ideia: manda até 10 números e recebe o resultado na resposta.

```http theme={null}
POST /v1/validations/phone
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

**Modo rápida** — formato internacional e tipo de linha:

```json theme={null}
{
  "phones": ["+5511999999999", "+14155552671"],
  "mode": "quick"
}
```

**Modo completa** — inclui checagem de WhatsApp:

```json theme={null}
{
  "phones": ["+5511999999999"],
  "mode": "full"
}
```

Resposta **200**:

```json theme={null}
{
  "success": true,
  "data": {
    "mode": "full",
    "total_credits_charged": 5,
    "results": [
      {
        "phone": "+5511999999999",
        "status": "valid",
        "phone_valid": true,
        "line_type": "mobile",
        "country_code": "BR",
        "whatsapp_registered": true,
        "reason": null,
        "credits_charged": 5
      }
    ]
  }
}
```

No modo `quick`, `whatsapp_registered` vem `null` (WhatsApp não é verificado).

### Telefone — lote grande (500 a 10.000)

```http theme={null}
POST /v1/validations/phone/batch
```

```json theme={null}
{
  "phones": ["+5511999999999", "+5511888888888"],
  "mode": "full"
}
```

<Warning>
  O batch de telefone exige **mínimo 500** números por job. Para listas menores, use o painel ou a rota síncrona.
</Warning>

Status do job:

```http theme={null}
GET /v1/validations/phone/batch/{jobId}
```

***

## CPF — consulta imediata (até 10)

Envie pares **CPF + data de nascimento** e escolha o modo. Padrão: `quick`.

```http theme={null}
POST /v1/validations/cpf
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

**Modo rápida** — valida dígitos do CPF e formato da data (mais barato):

```json theme={null}
{
  "items": [
    { "cpf": "12345678909", "birthDate": "1990-01-01" }
  ],
  "mode": "quick"
}
```

Resposta **200** (válido localmente):

```json theme={null}
{
  "success": true,
  "data": {
    "mode": "quick",
    "totalCreditsCharged": 1,
    "results": [
      {
        "cpf": "12345678909",
        "birthDate": "1990-01-01",
        "status": "valid",
        "resultCode": 8,
        "reason": null,
        "name": null,
        "socialName": null,
        "registrationStatus": null,
        "registeredBirthDate": null,
        "deceasedIndicator": null,
        "creditsCharged": 1
      }
    ]
  }
}
```

**Modo completa** — consulta na base oficial do governo (via parceria). Envie **vários pares na mesma requisição** — cada item retorna seu próprio `status`:

```json theme={null}
{
  "items": [
    { "cpf": "12345678909", "birthDate": "1990-01-01" },
    { "cpf": "11144477735", "birthDate": "2015-06-10" }
  ],
  "mode": "full"
}
```

Resposta **200** (adulto **encontrado** + menor **bloqueado** na mesma resposta):

```json theme={null}
{
  "success": true,
  "data": {
    "mode": "full",
    "totalCreditsCharged": 1800,
    "results": [
      {
        "cpf": "12345678909",
        "birthDate": "1990-01-01",
        "status": "found",
        "resultCode": 1,
        "reason": null,
        "name": "Maria da Silva",
        "socialName": null,
        "registrationStatus": { "code": "0", "description": "Regular" },
        "registeredBirthDate": "1990-01-01",
        "deceasedIndicator": null,
        "creditsCharged": 900
      },
      {
        "cpf": "11144477735",
        "birthDate": "2015-06-10",
        "status": "minorBlocked",
        "resultCode": 3,
        "reason": "Query blocked for minor data protected by LGPD.",
        "name": null,
        "socialName": null,
        "registrationStatus": null,
        "registeredBirthDate": null,
        "deceasedIndicator": null,
        "creditsCharged": 900
      }
    ]
  }
}
```

<Note>
  Outros status possíveis no mesmo array: `notFound` (CPF não encontrado), `invalid` (CPF ou data inválidos — **não cobra**). Veja [Consulta de CPF](/validations-api/como-funciona/introducao-cpf).
</Note>

Exemplo isolado — **não encontrado** (ainda cobra a consulta no modo completa):

```json theme={null}
{
  "success": true,
  "data": {
    "mode": "full",
    "totalCreditsCharged": 900,
    "results": [
      {
        "cpf": "98765432100",
        "birthDate": "1985-03-15",
        "status": "notFound",
        "resultCode": 2,
        "reason": "CPF not found.",
        "name": null,
        "socialName": null,
        "registrationStatus": null,
        "registeredBirthDate": null,
        "deceasedIndicator": null,
        "creditsCharged": 900
      }
    ]
  }
}
```

### CPF — lote grande (até 10.000)

```http theme={null}
POST /v1/validations/cpf/batch
```

```json theme={null}
{
  "items": [
    { "cpf": "12345678909", "birthDate": "1990-01-01" },
    { "cpf": "98765432100", "birthDate": "1985-03-15" }
  ],
  "mode": "full"
}
```

Resposta **200** (job enfileirado):

```json theme={null}
{
  "success": true,
  "data": {
    "jobId": "job_cpf_abc123",
    "status": "queued",
    "total": 2,
    "mode": "full"
  }
}
```

Consulte o progresso:

```http theme={null}
GET /v1/validations/cpf/batch/{jobId}
```

<Info>
  Diferente do batch de telefone, **não há mínimo de 500** — qualquer lote de 1 a 10.000 itens é aceito.
</Info>

***

## Painel (sem código)

| Add-on   | Caminho no painel                   | Limite             |
| -------- | ----------------------------------- | ------------------ |
| E-mail   | **Add-ons → Validação de e-mail**   | 10 por verificação |
| Telefone | **Add-ons → Validação de telefone** | 10 por verificação |
| CPF      | **Add-ons → Consulta de CPF**       | 10 por verificação |

Cole a lista, escolha **Rápida** ou **Completa** e veja os resultados à direita.

***

## Próximos passos

* [Validação de e-mail](/validations-api/como-funciona/introducao)
* [Validação de telefone](/validations-api/como-funciona/introducao-telefone)
* [Consulta de CPF](/validations-api/como-funciona/introducao-cpf)
* [Modos e cobrança](/validations-api/como-funciona/modos-e-cobranca)
* [Escopos da API Key](/validations-api/como-funciona/escopos-da-api-key)