Consulta em Tempo Real

Consulta o CPF na Receita Federal no momento da chamada e retorna nome, situação cadastral, código de controle e um comprovante da consulta.

Endpoint

Autenticação

Envie sua API Key no header x-api-key, a mesma da consulta simples. Não é preciso criar outra conta, outra chave ou outro plano. Veja Autenticação.

Sem o header, ou com uma chave inválida ou inativa, a API responde 401 com error como string:

{
  "success": false,
  "error": "API Key não fornecida"
}

Parâmetros

Headers

Body

Exemplos de requisição

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

Resposta de sucesso

HTTP 200 OK

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "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"
  }
}

Campos da resposta

Os campos marcados como opcionais podem não aparecer na resposta: emissionDate, emissionTime, controlCode e validationUrl dependem do que a Receita Federal devolve, e validationHtmlUrl depende da geração do comprovante. Trate a ausência deles no seu código.

Situação cadastral

O campo situation traz a situação cadastral como a Receita Federal informa, em maiúsculas. Só REGULAR indica CPF sem pendências.

Data de nascimento divergente

Se a data de nascimento não bate com o cadastro, ou se a Receita Federal recusa a consulta por outro motivo, a API responde 422 com a mensagem da própria Receita e não consome crédito:

{
  "success": false,
  "data": null,
  "error": {
    "message": "Data de nascimento informada está divergente da constante na base de dados da Secretaria da Receita Federal do Brasil."
  }
}

Créditos

Cada consulta em tempo real bem-sucedida consome 1,5 crédito do seu plano. Alguns planos têm custo próprio: o saldo e o custo aparecem no dashboard e em GET /quota.

Só há cobrança quando a Receita Federal responde e a resposta é interpretada. Data divergente (422), Receita fora do ar (502) e indisponibilidade temporária (503) não consomem crédito.

Quando o saldo não cobre o custo da consulta, em planos sem cobrança de excedente (overage), a API responde 403 com error como string, igual à consulta simples:

{
  "success": false,
  "error": "Limite de créditos excedido"
}

Latência

A resposta depende da Receita Federal, então leva segundos, não milissegundos. Use um timeout de pelo menos 60 segundos no seu cliente HTTP. Se o seu fluxo não pode esperar, faça a chamada de forma assíncrona ou use a consulta simples no caminho crítico.

Erros temporários

Respostas 502 e 503 indicam falha passageira na consulta à Receita Federal. Não consomem crédito e podem ser repetidas depois de alguns segundos. Exemplo:

{
  "success": false,
  "data": null,
  "error": {
    "message": "Falha ao consultar a Receita Federal."
  }
}

Códigos de status

Mensagens de 502 e 503:

Outras mensagens de indisponibilidade passageira podem aparecer em 502 e 503. Trate pelo status HTTP e repita a consulta após alguns segundos.

Mensagens de 400 e 422 de validação:

Quando usar cada consulta

Atualizado em 2 de outubro de 2026