Documentação da API

Segmenta a base da Receita Federal. Exige ao menos um filtro.

Custo: 1 crédito por registro entregue. Com apenas_total=true, devolve só a contagem e não cobra.

Filtros de múltipla escolha são repetidos na query string: ?ufs=ES&ufs=SP.

Escopo: empresas:read

Ficha cadastral completa. O CNPJ é validado pelos dígitos verificadores antes de consultar a base.

Custo: 1 crédito. Reconsultar o mesmo CNPJ no mesmo dia não cobra novamente.

Escopo: empresas:read

Cria um job assíncrono de exportação e devolve job_id.

Acompanhe em GET /mailing/{job_id}; ao concluir, o retorno traz arquivo_url.

Custo: o saldo é conferido aqui, mas a cobrança ocorre na conclusão, pela quantidade

efetivamente entregue — job que falha não cobra.

Escopo: mailing:export

Consulte periodicamente até status = concluido; então baixe arquivo_url.

Custo: 1 crédito por lead entregue, cobrado uma única vez — o polling não duplica.

Escopo: mailing:read

Devolve o arquivo da exportação concluída (ZIP contendo o CSV ou XLSX).

Disponível quando GET /mailing/{job_id} retornar status: concluido.

O campo arquivo_url daquela resposta já aponta para cá.

Custo: nenhum — a exportação foi cobrada na conclusão do job.

A resposta é binária: use -o arquivo.zip no curl ou trate como stream.

Escopo: mailing:read

Complementa a ficha da Receita com dados do bureau parceiro: porte e operação,

atividades secundárias, complementos cadastrais, quadro societário ampliado e sinais de risco.

Custo: 5 créditos.

Aceita apenas CNPJ. Dados pessoais de terceiros são descartados no servidor por allowlist;

o CPF de sócio vem completo (socios[].cpf). Requer credenciamento LGPD aprovado na sua conta.

Escopo: enriquecimento:read

Gera um código numérico, envia por SMS ao celular e devolve o id do envio. O código nunca volta na resposta.

Proteções: até 1 código a cada 30 s e 5 por hora para o mesmo celular. Só celulares (DDD + 9 dígitos).

Custo: 1 crédito de SMS por código. Falha de entrega devolve o crédito.

Escopo: sms:otp

Confere o código de um envio. Cada código aceita 5 tentativas, expira no prazo pedido e vale uma vez só.

Custo: sem custo. Escopo: sms:otp

Relatório de crédito do bureau: negativações (Pefin/Refin), protestos, cheques sem fundo,

dívidas vencidas, consultas de mercado recentes e quadro societário. Complementa /pessoas e

/enriquecimento (cadastro e contato) com a visão de risco — o dossiê unificado.

Por que POST: CPF/CNPJ não trafega em URL — caminho de requisição fica em log de servidor, proxy e CDN. O documento vai no corpo.

Custo: 10 créditos por documento por mês: repetir o mesmo documento no mês não cobra de novo, e dentro de 7 dias a resposta vem do cache.

Blocos pessoais do titular (filiação etc.) nunca saem pela API.

Escopo: credito:read

Consulta de pessoa física por CPF ou por telefone (busca reversa: telefone → dono), para KYC, análise de crédito e finalidades correlatas.

Acesso: exige o escopo pessoas:read e liberação individual da sua chave.

Ter o escopo não basta — a liberação é comercial e feita caso a caso.

Por que POST e não `GET /pessoas/{cpf}`: CPF não trafega em URL. O caminho da

requisição fica registrado em log de servidor, proxy, CDN e no header Referer —

lugares onde dado pessoal não deve estar em claro. No corpo, ele fica na conexão.

Finalidade define o que volta na resposta. Cada finalidade libera um conjunto de

campos, contratado com você — não é o mesmo para todos os clientes:

• ANALISE_CREDITO — Análise de crédito: Avaliação de risco para concessão de crédito ou limite.

• KYC_CADASTRO — Cadastro (KYC): Conferência cadastral e conheça-seu-cliente.

• COBRANCA_DIVIDA_PROPRIA — Cobrança de dívida própria: Localização de devedor de dívida da própria organização.

• PREVENCAO_FRAUDE — Prevenção à fraude: Verificação de indícios de fraude em cadastro ou transação.

Justificativa é opcional. Quando enviada, vai para a trilha de auditoria e deve ter

ao menos 15 caracteres, sem CPF, telefone ou e-mail (é campo livre, não depósito de dado

pessoal — e um número de 8+ dígitos é lido como telefone). Se você não enviar (ou enviar

algo inválido), a consulta usa automaticamente a justificativa padrão da sua conta e,

na falta dela, um texto padrão da finalidade — a chamada nunca falha por causa deste campo.

Custo: 15 créditos por consulta. Cobra a cada chamada, inclusive do mesmo CPF.

Abre a consulta e devolve um job_id na hora (milissegundos), sem esperar o bureau.

O resultado sai depois em GET /pessoas/jobs/{job_id}.

Para volume: dispare várias consultas sem prender uma conexão em cada, depois colete.

As mesmas travas da consulta síncrona valem aqui. Criar o job não consome crédito;

a cobrança ocorre quando o job é processado, uma única vez.

Estado e resultado de um job criado em /pessoas/consultar-async.

A primeira chamada que encontra o job pendente é quem executa a consulta — essa

absorve o tempo do bureau; as demais leem o resultado pronto. Refaça após retry_after

segundos enquanto o status for pendente ou processando.

status = concluido traz dados (o dossiê). O resultado é entregue uma vez e apagado:

guarde-o do seu lado. O crédito é cobrado no processamento, nunca duas vezes.

Mesma consulta, vários CPFs numa chamada. Feito para quem processa fila.

A resposta é sempre 200, com um item por CPF e o status de cada um. Um CPF

inválido no meio do lote não derruba os outros: você recebe exatamente quais

falharam e por quê, sem precisar reprocessar tudo.

CPF rejeitado na validação não consome crédito — não chegou a virar consulta.

Custo: 15 créditos por CPF consultado com sucesso; duplicata no mesmo lote cobra uma vez só.

O tamanho máximo do lote é definido no seu contrato (padrão 100 CPFs por chamada). Acima

dele a resposta é 422 PARAMETRO_INVALIDO informando o teto.

A finalidade e a justificativa valem para o lote inteiro.