Documentação da API de Consulta

Visão Geral

A API de Consulta permite buscar informações de pessoas a partir do CPF. Ela é simples, rápida e segura, retornando dados como nome, gênero e data de nascimento.

Quando o CPF ainda não está na nossa base, buscamos o registro em uma base externa de parceiros. Essa busca consome créditos — veja a seção Créditos de Consulta Externa.

Importante: Para utilizar esta API, você precisa de uma chave de API válida. Contrate um plano para obter sua chave.

Base URL

https://apicpf.com

Autenticação

Todas as requisições à API devem incluir uma chave de API válida no cabeçalho HTTP X-API-KEY.

// Exemplo de cabeçalho de autenticação
X-API-KEY: sua_chave_api_aqui
            

Alternativamente, você pode enviar a chave como parâmetro de consulta api_key:

https://apicpf.com/api/consulta?cpf=12345678900&api_key=sua_chave_api_aqui

Créditos de Consulta Externa

Além dos limites do seu plano, existe um segundo controle que vale apenas para uma situação específica: quando o CPF consultado ainda não está na nossa base e precisamos buscá-lo em uma base externa de parceiros.

O que consome crédito

Situação	Consome crédito?
CPF encontrado na nossa base	Não
CPF buscado na base externa e encontrado	Sim — 1 crédito
CPF buscado na base externa e não encontrado	Não
Requisição recusada por erro 400, 401, 403 ou 429	Não

Seus limites não mudam. Os limites diário e por minuto do seu plano continuam valendo exatamente como antes. Crédito é uma camada independente, que regula apenas o acesso à base externa.

Como os créditos são organizados

Os créditos ficam em lotes. Cada lote tem uma quantidade e uma data de validade próprias:

Ao contratar um plano, você recebe um lote com a quantidade prevista para ele, válido até o fim do ciclo da assinatura.
A cada renovação você recebe um lote novo. Os anteriores não são prorrogados nem zerados: o saldo é cumulativo, e cada lote vence na sua própria data.
Você também pode comprar pacotes avulsos, com quantidade e validade próprias, que somam ao saldo existente.
O consumo começa sempre pelo lote que vence primeiro, para que o saldo mais perecível seja usado antes de expirar.

Créditos dependem de assinatura ativa. Se o plano expirar, os créditos não são apagados, mas ficam indisponíveis até a renovação. A validade de cada lote continua correndo nesse período — renovando antes dessa data, o saldo volta a ficar disponível.

Acompanhando o saldo

Toda resposta da API traz o cabeçalho X-Credits-Remaining com o saldo total de créditos válidos da sua chave, somando todos os lotes. Use-o para monitorar o consumo sem precisar abrir o painel.

X-Credits-Remaining: 847

No painel, em Minhas Chaves API, você vê cada lote separadamente, com quantidade concedida, saldo restante e data de validade.

Endpoints

Consulta por CPF

GET /api/consulta

Consulta dados de uma pessoa a partir do CPF.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
cpf	string	Sim	CPF da pessoa, com ou sem formatação (apenas números)

curl -X GET "https://apicpf.com/api/consulta?cpf=12345678900" \
     -H "X-API-KEY: sua_chave_api_aqui"
                    

// Usando Fetch API
fetch('https://apicpf.com/api/consulta?cpf=12345678900', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'sua_chave_api_aqui'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Erro:', error));
                    

// Usando cURL
$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://apicpf.com/api/consulta?cpf=12345678900');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: sua_chave_api_aqui'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

curl_close($ch);
                    

Resposta de Sucesso

200 OK

{
    "code": 200,
    "data": {
        "cpf": "12345678900",
        "nome": "João da Silva",
        "genero": "M",
        "data_nascimento": "1985-07-15"
    }
}
            

Campo	Descrição
code	Código de status HTTP da resposta
data.cpf	CPF completo com 11 dígitos (preenchido com zeros à esquerda se necessário)
data.nome	Nome completo da pessoa
data.genero	Gênero - "M" (Masculino), "F" (Feminino) ou "I" (Indefinido/Outro)
data.data_nascimento	Data de nascimento no formato YYYY-MM-DD

Respostas de Erro

400 Bad Request - CPF não informado

{
    "code": 400,
    "message": "O parâmetro CPF é obrigatório"
}
            

400 Bad Request - CPF com formato inválido

{
    "code": 400,
    "message": "O CPF deve conter exatamente 11 dígitos"
}
            

400 Bad Request - CPF reprovado na validação do dígito verificador

{
    "code": 400,
    "message": "CPF inválido"
}
            

404 Not Found - CPF não encontrado

{
    "code": 404,
    "message": "Pessoa não encontrada com o CPF informado"
}
            

402 Payment Required - Sem créditos para consultar a base externa

{
    "code": 402,
    "message": "Sem créditos disponíveis para consulta externa. Adquira créditos ou renove seu plano em www.apicpf.com"
}
            

O 402 não interrompe sua integração. Ele acontece apenas quando o CPF consultado não está na nossa base e não há saldo para buscá-lo na base externa. Consultas de CPFs já presentes na nossa base continuam sendo atendidas normalmente, com 200, e seus limites diário e por minuto seguem inalterados. Para voltar a alcançar a base externa, adquira um pacote de créditos ou renove seu plano.

401 Unauthorized - API Key não fornecida

{
    "code": 401,
    "message": "API key não fornecida"
}
            

401 Unauthorized - API Key inválida

{
    "code": 401,
    "message": "API key inválida"
}
            

403 Forbidden - API Key expirada

{
    "code": 403,
    "message": "API key expirada"
}
            

429 Too Many Requests - Limite diário excedido

{
    "code": 429,
    "message": "Limite diário excedido"
}
            

429 Too Many Requests - Limite por minuto excedido

{
    "code": 429,
    "message": "Limite por minuto excedido. Diminua a frequência de requisições ou contrate um plano PRO em www.apicpf.com"
}
            

429 Too Many Requests - Limite de consultas repetidas com o mesmo CPF excedido

{
    "code": 429,
    "message": "Limite de consultas repetidas excedido"
}
            