—Documentação

Endpoint.

Um único endpoint REST. O conjunto de campos retornados é definido pelo seu plano — sem parâmetros adicionais, sem escolhas por chamada.

Visão geral

A API expõe um único recurso: GET /v1/cpf/{cpf}. O CPF aceita formato 000.000.000-00 ou apenas dígitos. Toda a autenticação acontece via Authorization: Bearer sk_live_….

O plano do workspace determina, automaticamente, quais campos vêm na resposta. Planos mais altos sempre incluem todos os campos dos planos abaixo. Para mudar o conjunto de campos basta trocar de plano.

Requisição

GET/v1/cpf/{cpf}

curl https://api.cpfhub.com/v1/cpf/52998224725 \
  -H "Authorization: Bearer sk_live_…" \
  -H "Accept: application/json"

A resposta sempre inclui request_id (também no header x-request-id) — mantenha junto dos seus logs para rastreabilidade em suporte.

Estrutura da resposta

Toda resposta de sucesso (HTTP 200) segue o mesmo invólucro. O objeto data é onde os campos do CPF aparecem.

200 OK · invólucro

{
  "object": "cpf.lookup",
  "request_id": "req_xxx",
  "endpoint": "cpf.full",
  "env": "live",
  "data": { /* campos conforme o plano — ver tabela abaixo */ }
}

Campo	Tipo	A partir do tier	Descrição
cpf	string	A · Básica	CPF formatado (000.000.000-00).
nome	string	A · Básica	Nome completo do titular.
nascimento	string \| null	B · Padrão	Data de nascimento no formato DD/MM/AAAA.
idade	number \| null	B · Padrão	Idade calculada em anos completos.
mae	string \| null	C · Completa	Nome completo da mãe.
genero	"M" \| "F" \| null	C · Completa	Gênero declarado no cadastro.
status	string \| null	D · Receita	Situação cadastral (REGULAR, SUSPENSA, CANCELADA, NULA, PENDENTE, FALECIDA).
statusUpdatedAt	string \| null	D · Receita	Data da última atualização da situação (AAAA-MM-DD).
emails	string[]	E · E-mails	Lista de e-mails associados ao titular.
phones	object[]	F · Telefones	Telefones associados (número, operadora, tipo, indicador de WhatsApp).
addresses	object[]	G · Cadastro pleno	Endereços associados (CEP, UF, cidade, bairro, logradouro, número, complemento).

Tiers e planos

Cada plano entrega um tier fixo de dados. O campo endpoint da resposta indica o nome técnico do tier.

Tier	Identificador	Inclui (acumulativo)	Planos com este tier
A · Básica	cpf.basic	Nome	—
B · Padrão	cpf.standard	Nome + data de nascimento	—
C · Completa	cpf.full	+ nome da mãe e gênero	Sandbox, Dev
D · Receita	cpf.receita	+ situação cadastral	Starter
E · E-mails	cpf.emails	+ e-mails associados	Growth
F · Telefones	cpf.phones	+ telefones associados	Business
G · Cadastro pleno	cpf.complete	+ endereços	Scale, Unlimited, Enterprise

Resposta · A · Básica (cpf.basic)

200 OK

{
  "object": "cpf.lookup",
  "request_id": "req_8fc0658dc225c509",
  "endpoint": "cpf.basic",
  "env": "live",
  "data": {
    "cpf": "529.982.247-25",
    "nome": "Maria Aparecida da Silva"
  }
}

Resposta · B · Padrão (cpf.standard)

200 OK

{
  "object": "cpf.lookup",
  "request_id": "req_8fc0658dc225c509",
  "endpoint": "cpf.standard",
  "env": "live",
  "data": {
    "cpf": "529.982.247-25",
    "nome": "Maria Aparecida da Silva",
    "nascimento": "12/04/1987",
    "idade": 38
  }
}

Resposta · C · Completa (cpf.full)

200 OK

{
  "object": "cpf.lookup",
  "request_id": "req_8fc0658dc225c509",
  "endpoint": "cpf.full",
  "env": "live",
  "data": {
    "cpf": "529.982.247-25",
    "nome": "Maria Aparecida da Silva",
    "nascimento": "12/04/1987",
    "idade": 38,
    "mae": "Antônia da Silva",
    "genero": "F"
  }
}

Resposta · D · Receita (cpf.receita)

200 OK

{
  "object": "cpf.lookup",
  "request_id": "req_8fc0658dc225c509",
  "endpoint": "cpf.receita",
  "env": "live",
  "data": {
    "cpf": "529.982.247-25",
    "nome": "Maria Aparecida da Silva",
    "nascimento": "12/04/1987",
    "idade": 38,
    "mae": "Antônia da Silva",
    "genero": "F",
    "status": "REGULAR",
    "statusUpdatedAt": "2026-09-02"
  }
}

Resposta · E · E-mails (cpf.emails)

200 OK

{
  "object": "cpf.lookup",
  "request_id": "req_8fc0658dc225c509",
  "endpoint": "cpf.emails",
  "env": "live",
  "data": {
    "cpf": "529.982.247-25",
    "nome": "Maria Aparecida da Silva",
    "nascimento": "12/04/1987",
    "idade": 38,
    "mae": "Antônia da Silva",
    "genero": "F",
    "status": "REGULAR",
    "statusUpdatedAt": "2026-09-02",
    "emails": ["maria@example.com", "msilva@trabalho.com.br"]
  }
}

Resposta · F · Telefones (cpf.phones)

200 OK

{
  "object": "cpf.lookup",
  "request_id": "req_8fc0658dc225c509",
  "endpoint": "cpf.phones",
  "env": "live",
  "data": {
    "cpf": "529.982.247-25",
    "nome": "Maria Aparecida da Silva",
    "nascimento": "12/04/1987",
    "idade": 38,
    "mae": "Antônia da Silva",
    "genero": "F",
    "status": "REGULAR",
    "statusUpdatedAt": "2026-09-02",
    "emails": ["maria@example.com"],
    "phones": [
      { "number": "(11) 98765-4321", "operator": "VIVO", "type": "MÓVEL", "whatsapp": true },
      { "number": "(11) 3322-1100", "operator": null, "type": "FIXO", "whatsapp": false }
    ]
  }
}

Resposta · G · Cadastro pleno (cpf.complete)

200 OK

{
  "object": "cpf.lookup",
  "request_id": "req_8fc0658dc225c509",
  "endpoint": "cpf.complete",
  "env": "live",
  "data": {
    "cpf": "529.982.247-25",
    "nome": "Maria Aparecida da Silva",
    "nascimento": "12/04/1987",
    "idade": 38,
    "mae": "Antônia da Silva",
    "genero": "F",
    "status": "REGULAR",
    "statusUpdatedAt": "2026-09-02",
    "emails": ["maria@example.com"],
    "phones": [
      { "number": "(11) 98765-4321", "operator": "VIVO", "type": "MÓVEL", "whatsapp": true }
    ],
    "addresses": [
      {
        "postalCode": "05432-010",
        "state": "SP",
        "city": "São Paulo",
        "neighborhood": "Vila Madalena",
        "street": "Rua das Acácias",
        "number": "120",
        "complement": null
      }
    ]
  }
}

Validação de CPF

A API valida o dígito verificador antes de qualquer consulta. CPF inválido retorna 422 Unprocessable Entity com error: "invalid_cpf" e não consome cota.

CPFs com dígitos repetidos (000.000.000-00 etc.) são rejeitados como inválidos, mesmo quando os dígitos verificadores são aritmeticamente corretos.

Erros possíveis

Toda resposta de erro inclui error, message e request_id. Veja o catálogo completo em /docs/erros.

422 Unprocessable Entity

{
  "error": "invalid_cpf",
  "message": "CPF inválido. Verifique os dígitos verificadores.",
  "request_id": "req_xxx",
  "documentation_url": "https://cpfhub.com/docs/erros"
}