Consulta de CPF — Irrestrita
Esta modalidade consulta a situação cadastral de um CPF diretamente em uma base de dados irrestrita. É a opção indicada para consultas críticas que exigem maior cobertura de campos como o nome social.
A consulta vai à base de dados irrestrita autenticada via credenciais comerciais. Cada chamada percorre toda a cadeia até a fonte de dados. O contrato de resposta é o mesmo da consulta Receita Federal, com maior probabilidade de retorno do campo socialName quando ele consta na base.
1. Base para a consulta
Para consultar a situação cadastral de um CPF nesta modalidade, informe o número do CPF e a data de nascimento da pessoa. O endpoint é único e está descrito abaixo.
| Método | URL |
|---|---|
| GET | https://naturalperson.api.nfe.io/v1/naturalperson/serpro/status/{federalTaxNumber}/{birthDate} |
Parâmetros de caminho:
federalTaxNumber— CPF sem máscara, somente dígitos (sem pontos nem traços).birthDate— data de nascimento no formatoaaaa-mm-dd.
Autenticação
Você precisa de uma chave de API. Crie sua conta em nossa plataforma e gere a chave conforme chaves de autenticação. A API aceita três formas equivalentes de envio:
| Modo | Exemplo |
|---|---|
Header Authorization | Authorization: Bearer {apiKey} |
Header X-NFEIO-APIKEY | X-NFEIO-APIKEY: {apiKey} |
| Query string | ?apiKey={apiKey} |
Exemplo de chamada
curl -X GET \
"https://naturalperson.api.nfe.io/v1/naturalperson/serpro/status/72946154***/****-**-**" \
-H "Authorization: Bearer 5th************"
Esta modalidade depende de habilitação comercial na conta NFE.io. Se a consulta retornar 403, verifique a habilitação com seu gerente comercial.
2. Quando usar esta modalidade
Use a consulta Irrestrita quando você precisa de cobertura mais ampla de campos como socialName. O custo por chamada é maior.
| Aspecto | Irrestrita | Receita Federal |
|---|---|---|
| Fonte | Base de dados irrestrita (comercial) | Página pública da RFB (coleta direta) |
| Latência | Consistente | Pode variar com o portal público da RFB |
socialName | Confiável quando consta na base | Pode não vir |
| Custo | Maior (consulta comercial) | Menor |
| Recomendado para | Consultas críticas com cobertura ampla | Volume alto e menor custo |
Para a outra modalidade, veja Consulta de CPF — Receita Federal.
3. Dados de retorno
A API responde com os seguintes códigos HTTP:
| Status | Significado |
|---|---|
| 200 | Sucesso na requisição |
| 400 | Parâmetro informado de forma incorreta |
| 401 | Autenticação inválida |
| 403 | Sem permissão para o recurso |
| 404 | CPF não encontrado ou data de nascimento divergente |
| 500 | Erro no processamento |
| 503 | Temporariamente indisponível |
O payload de retorno segue o formato abaixo.
{
"createdOn": "2026-05-27T13:09:16.346Z",
"name": "string",
"socialName": "string",
"federalTaxNumber": "string",
"birthOn": "1980-01-01T00:00:00.000Z",
"status": "Regular"
}
Dicionário de campos
createdOn string($date-time) Data da consulta.
name string Nome da pessoa consultada.
socialName string? Nome social. Retornado com mais frequência nesta modalidade, pois a base irrestrita o entrega quando ele consta no cadastro do contribuinte.
federalTaxNumber string CPF consultado.
birthOn string($date-time) Data de nascimento.
status string(enum) Situação cadastral do CPF.
| Texto do retorno | Significado |
|---|---|
| Unknown | Desconhecido |
| Regular | Regular / ativo |
| Null | Nulo |
| Suspended | Suspenso |
| Canceled | Cancelado |
| RegularizationPending | Pendente de regularização |
| OwnerDeceased | Titular falecido |