Documentação da API

Um único endpoint, autenticado por chave. Todas as respostas são JSON.

Autenticação

Envie sua chave no cabeçalho x-api-key em todas as requisições. Chaves ausentes, inválidas ou revogadas recebem 401. Gere e revogue chaves no painel; mantenha-as apenas no seu servidor.

x-api-key: cpf_live_••••••••••••••••

Endpoints

Há dois caminhos: a consulta rápida na base interna (só CPF) e a consulta oficial (CPF + data de nascimento). Os dois têm versão em lote, com até 1.000 CPFs por requisição. Todo CPF é higienizado (pontos e traço são removidos) antes da busca.

Consulta na base interna

O 404 de cache miss não é erro de CPF: significa só que o registro ainda não está na nossa base. O corpo traz code: "CACHE_MISS". O dado em cache vale por até 30 dias.

curl https://api.brazid.com/v1/cpf/52998224725 \
  -H "x-api-key: $BRAZID_API_KEY"

Consulta em lote

No lote da base interna a resposta é imediata. CPFs repetidos contam uma vez. Sem excedente, se o saldo não cobrir todos os encontrados a requisição inteira responde 402 e nada é cobrado.

curl -X POST https://api.brazid.com/v1/cpf/batch \
  -H "x-api-key: $BRAZID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cpfs": ["529.982.247-25", "11144477735"] }'

{
  "success": true,
  "found": [
    {
      "cpf": "52998224725",
      "name": "MARIA SOUZA LIMA",
      "birthdate": "26/11/1982",
      "situation": "REGULAR"
    }
  ],
  "missing": [
    "11144477735"
  ],
  "invalid": [],
  "credits_remaining": 48
}

Como funciona o lote oficial

O que já está no cache é respondido na hora. O restante vai para a fonte oficial em segundo plano, com concorrência limitada. Itens inválidos, não encontrados e falhas do provedor não cobram, e você pode reenviar só os que falharam. Os resultados ficam disponíveis por 24 horas. Se você tiver um webhook configurado, enviamos o evento batch.completed (sem dados pessoais) quando o lote termina.

curl -X POST https://api.brazid.com/v1/cpf/batch/process \
  -H "x-api-key: $BRAZID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{ "cpf": "529.982.247-25", "birthdate": "1982-11-26" }, { "cpf": "11144477735", "birthdate": "1990-05-02" }]'

{
  "success": true,
  "batch_id": "0c1e…",
  "status": "processing",
  "total": 2,
  "processed": 1,
  "status_url": "/v1/cpf/batch/0c1e…"
}

Consultar um CPF

Envie cpf (com ou sem pontuação) e birthdate (AAAA-MM-DD), ambos obrigatórios. Os dois são sanitizados e validados antes de qualquer consulta; a data de nascimento precisa conferir com a do titular, senão a resposta é 404.

POST /v1/cpf

curl -X POST https://api.brazid.com/v1/cpf \
  -H "x-api-key: $BRAZID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cpf": "529.982.247-25", "birthdate": "1982-11-26" }'

Resposta

credits_remaining pode ser ocultado nas configurações do painel. gender e deceased podem ser null quando a fonte não informa.

{
  "success": true,
  "data": {
    "cpf": "52998224725",
    "name": "MARIA SOUZA LIMA",
    "birthdate": "26/11/1982",
    "day": 26,
    "month": 11,
    "year": 1982,
    "gender": "M",
    "deceased": false,
    "situation": "REGULAR"
  },
  "credits_remaining": 49
}

cpf

CPF sanitizado, 11 dígitos.

name

Nome do titular, em maiúsculas.

birthdate

Data de nascimento no formato DD/MM/AAAA. day, month e year trazem as partes numéricas.

gender

M, F ou null.

situation

Situação cadastral em texto (ex.: REGULAR, TITULAR FALECIDO); null quando a fonte não informa.

deceased

true quando a situação cadastral indica óbito; null quando desconhecido.

credits_remaining

Saldo após esta consulta (cota mensal + créditos bônus).

Erros

Nenhuma resposta 4xx ou 5xx consome crédito ou gera cobrança de excedente.

Limites de requisição

Cada chave tem um limite por segundo conforme o plano: 5 (Gratuito), 20 (Pro 200), 50 (Pro 1.000), 100 (Pro 5.000), 200+ (Corporativo). As respostas trazem X-RateLimit-Limit, X-RateLimit-Remaining e, em caso de 429, Retry-After em segundos.

Webhooks de consumo

Cadastre uma URL HTTPS no painel para receber o evento usage.threshold_reached quando o consumo atingir 80% e 95% da cota. Cada envio traz o cabeçalho x-brazid-signature: t=<timestamp>,v1=<HMAC-SHA256 de "timestamp.corpo">, calculado com o segredo do seu webhook.

{
  "type": "usage.threshold_reached",
  "threshold": 80,
  "used_percent": 80,
  "monthly_credits": 500,
  "auto_charge_enabled": true,
  "period_end": "2026-11-13T00:00:00.000Z"
}