Sobre esta API

Dados cadastrais de uma pessoa física a partir do CPF: nome, nome social, data de nascimento, gênero e a situação do CPF na Receita Federal, com data de inscrição e ano de óbito quando houver.

Envie um JSON com cpf, com ou sem pontuação, e, se tiver, birth_date (AAAA-MM-DD): ela é conferida em data_nascimento_confere e amplia a cobertura da consulta. Campo que o cadastro não informa volta null.

CPF sem cadastro na Receita volta com found: false e é cobrado: a consulta foi feita. Sem birth_date, CPF que só pode ser conferido com ela volta 400 (birth_date_required), e CPF com dígito verificador inválido, 422: nenhum dos dois é cobrado.

Fonte dos dados

Cadastro de Pessoas Físicas (CPF) · Atualização: tempo real

Requisição

POST /api/v1/cpf/lookup

Autenticação HTTP Basic: public_key:secret_key em Base64. Guarde a chave secreta no servidor.

Cabeçalho	Descrição
`Authorization` Obrigatório	Chave de API em Basic: `public_key:secret_key` em Base64.
`X-Project-Id` Opcional	Projeto que recebe a chamada. Sem ele, vale o projeto padrão da conta.
`Idempotency-Key` Opcional	Repetir a mesma chave em até 24 horas devolve a resposta anterior, sem executar nem cobrar de novo.

Parâmetros

Campo	Tipo e local	Descrição
`cpf` Obrigatório	stringbody	Com ou sem pontuação. O dígito verificador é conferido antes da consulta. Exemplo: `52998224725`
`birth_date` Opcional	stringbody	Data de nascimento no formato `AAAA-MM-DD`. Exemplo: `1990-03-15`

1curl --request POST 'https://api.apifordevs.com/api/v1/cpf/lookup' \
2  --user "afd_live_pk_...:$AFD_SECRET_KEY" \
3  --header "X-Project-Id: $AFD_PROJECT_ID" \
4  --header 'Content-Type: application/json' \
5  --data '{"cpf":"52998224725","birth_date":"1990-03-15"}'

1import os
2import requests
3
4response = requests.request(
5    "POST",
6    "https://api.apifordevs.com/api/v1/cpf/lookup",
7    auth=("afd_live_pk_...", os.environ["AFD_SECRET_KEY"]),
8    headers={"X-Project-Id": os.environ["AFD_PROJECT_ID"]},
9    json={"cpf": "52998224725", "birth_date": "1990-03-15"},
10    timeout=30,
11)
12response.raise_for_status()
13print(response.json())

1const response = await fetch("https://api.apifordevs.com/api/v1/cpf/lookup", {
2  method: "POST",
3  headers: {
4    Authorization: "Basic " + Buffer.from(
5      "afd_live_pk_...:" + process.env.AFD_SECRET_KEY
6    ).toString("base64"),
7    "X-Project-Id": process.env.AFD_PROJECT_ID,
8    "Content-Type": "application/json",
9  },
10  body: JSON.stringify({"cpf":"52998224725","birth_date":"1990-03-15"}),
11  signal: AbortSignal.timeout(30000),
12});
13if (!response.ok) throw new Error(`HTTP ${response.status}`);
14console.log(await response.json());

Campos de resposta

Campos e tipos publicados no catálogo desta API.

Encontradofoundboolean
CPFcpfstring
Nomenomestring
Nome socialnome_socialstring
Data de nascimentodata_nascimentostring
Gênerogenerostring: M ou F, quando informado.
Situação cadastralsituacao_cadastralstring: Situação do CPF na Receita Federal, quando informada: REGULAR, SUSPENSA, PENDENTE DE REGULARIZAÇÃO, TITULAR FALECIDO, CANCELADA POR MULTIPLICIDADE, CANCELADA DE OFÍCIO ou NULA.
Data de inscriçãodata_inscricaostring
Ano de óbitoano_obitointeger
Data de nascimento conferedata_nascimento_confereboolean: Se a birth_date enviada confere com o cadastro. Nulo quando ela não é enviada.

Exemplo de resposta

1{
2  "success": true,
3  "code": 200,
4  "code_message": "A requisição foi processada com sucesso.",
5  "errors": [],
6  "header": null,
7  "data_count": 1,
8  "data": [
9    {
10      "found": true,
11      "cpf": "52998224725",
12      "nome": "MARIA DA SILVA SANTOS",
13      "nome_social": null,
14      "data_nascimento": "1990-03-15",
15      "genero": "F",
16      "situacao_cadastral": "REGULAR",
17      "data_inscricao": "2008-06-10",
18      "ano_obito": null,
19      "data_nascimento_confere": true
20    }
21  ]
22}

Respostas e cobrança

HTTP	Descrição	Cobrança
`200`	Sucesso. CPF sem cadastro na Receita também é `200`, com `found: false`, e é cobrado.	Sujeita à cobrança
`400` `birth_date_required`	O CPF só pode ser conferido com a data de nascimento: envie `birth_date`. Não é cobrada.	Sem cobrança
`401` `unauthorized`	Credencial ausente, inválida ou revogada.	Sem cobrança
`402` `payment_required`	Saldo insuficiente ou limite de gasto diário atingido.	Sem cobrança
`403` `forbidden` `ip_not_allowed` `test_key_cannot_run_live`	E-mail da conta não verificado, chave sem escopo para o serviço, IP fora da allowlist do projeto ou chave de teste sem `dev_mode=true`.	Sem cobrança
`409` `conflict`	Requisição com a mesma `Idempotency-Key` ainda em andamento.	Sem cobrança
`422` `validation_error`	CPF com dígito verificador inválido ou data de nascimento fora do formato. Não é cobrada.	Sem cobrança
`429` `rate_limit_exceeded`	Limite de requisições por minuto da chave atingido.	Sem cobrança
`500` `internal_error`	Falha interna.	Sem cobrança
`503` `service_unavailable` `upstream_error`	Serviço desativado (`service_unavailable`), ou a consulta do CPF não respondeu a tempo (`upstream_error`). Não é cobrada; com `upstream_error`, pode ser repetida.	Sem cobrança

Casos de uso

Onboarding e KYC

Conferir o nome e a data de nascimento informados contra o CPF antes de abrir a conta, sem pedir documento a mais.

Antifraude em crédito

Barrar CPF suspenso, cancelado ou de titular falecido antes de aprovar crédito, financiamento ou parcelamento.

Preenchimento de cadastro

Completar o nome a partir do CPF digitado, sem o usuário redigitar.

Notas de integração

O CPF vai no corpo, nunca na URL: é dado pessoal e não deve ficar em log de acesso.
Consulte CPF de terceiros só com finalidade e base legal, como pede a LGPD.

Cadastro de Pessoa Física