Consulta em Tempo Real

Envie o CPF e a data de nascimento e receba nome, data de nascimento, ano do óbito, situação cadastral, código de controle e comprovante, direto da Receita Federal. Custa 1,5 crédito por consulta.

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Consulta em Tempo Real e cole no seu assistente.

Abrir no Cursor

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da Consulta em Tempo Real e cole no seu assistente.

Abrir no Cursor

Não é essa? Compare as consultas.

Endpoint

POSThttps://api.cpfhub.io/cpf/realtime

Parâmetros

Onde	Nome	Obrigatório	Descrição
Header	`x-api-key`	Sim	Sua API Key, a mesma da Consulta Simples. Veja Autenticação.
Header	`Content-Type`	Sim	`application/json`
Body	`cpf`	Sim	CPF com ou sem formatação: `12345678909` ou `123.456.789-09`
Body	`birthDate`	Sim	Data de nascimento, 8 dígitos (dia, mês, ano): `DD/MM/AAAA` ou `DDMMAAAA`. Separadores são ignorados. Ano entre 1900 e o atual.

Exemplo

Os exemplos leem a chave de CPFHUB_API_KEY, usam timeout de 60 s e tratam os erros pelo status HTTP.

curl --max-time 60 -X POST "https://api.cpfhub.io/cpf/realtime" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cpf": "12345678909",
    "birthDate": "15/06/1990"
  }'

Resposta

HTTP 200 OK

JSON

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "deathYear": null,
    "situation": "REGULAR",
    "emissionDate": "02/10/2026",
    "emissionTime": "14:15:16",
    "controlCode": "ABCD.1234.EFGH.5678",
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678909&cc=ABCD1234EFGH5678&de=02102026&he=141516&dv=09&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/12345678909/1790950516000"
  }
}

Campo	Tipo	Descrição
`data.cpf`	`string`	CPF consultado, 11 dígitos sem máscara
`data.name`	`string`	Nome como consta na Receita Federal, em maiúsculas
`data.birthDate`	`string`	Data de nascimento, `DD/MM/AAAA`
`data.deathYear`	`integer \| null`	Ano do óbito. Sempre presente: `null` quando não há óbito registrado ou quando o valor recebido é inválido. Um valor válido tem 4 dígitos, fica entre 1900 e o ano atual e não pode ser anterior ao ano de nascimento.
`data.situation`	`string`	Situação cadastral (tabela abaixo)
`data.emissionDate`	`string`	Data de emissão do comprovante, `DD/MM/AAAA`. Opcional.
`data.emissionTime`	`string`	Hora de emissão, `HH:MM:SS`. Opcional.
`data.controlCode`	`string`	Código de controle do comprovante (`XXXX.XXXX.XXXX.XXXX`). Opcional.
`data.validationUrl`	`string`	Link de conferência no site da Receita Federal (destino do QR code). Opcional.
`data.validationHtmlUrl`	`string`	Comprovante guardado pela CPFHub.io (HTML com QR code). Opcional.

Campos opcionais podem não vir: dependem do que a Receita Federal devolve e da geração do comprovante. deathYear não é opcional: o campo sempre vem, com um inteiro válido ou null.

Situação cadastral

`situation`	Significado
`REGULAR`	CPF em ordem, sem pendências
`PENDENTE DE REGULARIZAÇÃO`	Falta entregar declaração ou atualizar o cadastro
`SUSPENSA`	Cadastro incorreto ou incompleto
`CANCELADA`	Inscrição encerrada (decisão administrativa, judicial ou multiplicidade)
`NULA`	Inscrição anulada por fraude
`TITULAR FALECIDO`	Óbito registrado no cadastro

Só REGULAR indica CPF sem pendências. Todas as situações vêm com 200 e consomem crédito.

Erros

Status	Quando acontece	O que fazer
`400`	CPF sem 11 dígitos, ou `birthDate` ausente ou inválida	Corrija o body. Não repita.
`401`	API Key ausente, inválida ou inativa (`error` string)	Confira o header `x-api-key`.
`403`	Créditos insuficientes sem overage (`error.message`: `"Limite de créditos excedido"`) ou conta inativa/bloqueada (`error` string)	Recarregue créditos ou fale com o suporte. Não repita.
`422`	Dígito verificador inválido, ou a Receita Federal recusou a consulta (ex.: data de nascimento divergente)	Corrija o CPF ou a data. Não consome crédito. Trate pelo status, não pelo texto (vem da Receita).
`429`	Limite por minuto excedido (5/min no padrão)	Espere os segundos do header `Retry-After`. Não consome crédito.
`500`	Erro interno	Reporte se persistir.
`502`, `503`	Falha passageira na Receita Federal ou na reserva de créditos	Repita com espera crescente (2 s, 4 s, 8 s). Não consome crédito.

Formato do erro, retentativas e como testar sem gastar créditos: Códigos de Erro. Limite por minuto e créditos: Limites de Uso.

Detalhes

Custo: 1,5 crédito por consulta com 200, em qualquer situação cadastral. Alguns planos têm custo próprio: consulte o do seu plano no dashboard.
Tempo de resposta: cerca de 1 segundo (tempo típico, não um SLA). Use timeout de pelo menos 60 s. Se o fluxo não pode esperar, chame de forma assíncrona.
Sem lote: a consulta é feita CPF a CPF.
Não repita depois de timeout local: o POST não é idempotente. A consulta pode ter sido concluída e cobrada. Confira o saldo em GET /quota antes de tentar de novo.
Dados de exemplo: o CPF 12345678909 e os dados acima são fictícios.

⚠

O link do comprovante é público

Qualquer pessoa com o link de validationHtmlUrl abre o comprovante (nome, CPF e situação). Trate como dado pessoal: guarde só no back-end, não registre em logs e não exponha no front-end.

Atualizado em 4 de outubro de 2026