Consulta em Lote

Sua base inteira,
conferida de uma vez.

Mande até 10.000 CPFs num único job e acompanhe o processamento. Você paga só pelos que forem encontrados, e nada pelos que não existirem.

Começar grátis Falar sobre volume

Mesma chave e mesmo crédito da Consulta Simples. Pelo dashboard ou pela API.

O que você recebe

Dez mil consultas. Uma requisição.

O trabalho de orquestrar fila, paralelismo e retentativa fica do nosso lado.

Um job, até 10.000 CPFs

Você manda a lista inteira numa requisição e recebe um jobId na hora. Nada de disparar dez mil chamadas e torcer para o seu servidor aguentar.

Resultado parcial enquanto processa

O job não é uma caixa preta. A cada consulta ao status você já vê quantos foram processados, quantos encontrou e os registros prontos até ali.

Cobrança só pelo que achou

Cada CPF encontrado consome 1 crédito. Não encontrado e inválido não consomem nada. Base suja não vira fatura inflada.

Sem código, se você preferir

O dashboard aceita CSV ou TXT, detecta o separador e a coluna de CPF sozinho, e exporta o resultado. Dá para colar a lista direto num campo de texto.

Acompanhamento

Você sabe onde o job está.

Três estados possíveis e cinco contadores. Sem adivinhar se travou ou se ainda está rodando.

processing

O job está rodando. Consultar o status devolve o progresso e os registros já prontos.

done

Terminou. A resposta traz o resultado completo, item por item.

failed

Algo travou. Um job parado há mais de 10 minutos é marcado automaticamente, em vez de ficar pendurado para sempre.

Contadores do job

total_records

Quantos CPFs válidos entraram no job.

processed

Quantos já foram consultados.

found

Quantos existem na base. É o que você paga.

not_found

Quantos não têm registro. Não cobram.

skipped

Quantos ficaram de fora por falta de crédito.

Como cobra

Você paga pelos CPFs
que existem.

Numa base antiga, boa parte dos registros não vai existir mais. Em muitos serviços, cada uma dessas tentativas é cobrada mesmo assim. Aqui, a tentativa sem resultado não entra na conta.

1 crédito

por CPF encontrado, igual à Consulta Simples

R$ 0

por CPF não encontrado ou inválido

10.000

CPFs por job, quantos jobs você precisar

Se o crédito acabar no meio do lote, os CPFs restantes voltam como skipped. Não são consultados nem cobrados, e você reprocessa quando quiser.

Ver planos

Onde usar

Quando o problema é a base toda.

Situações em que consultar um CPF por vez levaria semanas e ninguém faria.

Limpar base legada

Cadastro antigo com nome digitado errado e data de nascimento faltando. Passa a base inteira e normaliza de uma vez.

Migração de sistema

Antes de levar o cadastro para o sistema novo, confirme quais CPFs existem de fato e o que fazer com o resto.

Prevenção de fraude na base ativa

Encontre CPFs inexistentes, de titulares falecidos ou com nome divergente antes que virem prejuízo.

Auditoria periódica de cadastro

Rode o lote todo mês e acompanhe quantos registros da sua base deixaram de bater com o dado oficial.

Conciliação de carteira

Antes de cobrar, renovar ou repassar comissão, confirme que os titulares da carteira são quem o cadastro diz.

Due diligence em fusões e aquisições

Herdou a carteira de clientes de outra empresa? O lote diz em horas quantos cadastros estão corretos.

Como funciona

Manda e acompanha. Só isso.

O job é assíncrono, então a sua requisição não fica pendurada esperando dez mil consultas terminarem.

Envie a lista

Um POST com o array de CPFs. A resposta volta na hora com o jobId, sem prender a sua requisição enquanto processa.

Acompanhe o job

Consulte o jobId quando quiser. Cada consulta traz o progresso e os registros já concluídos, até o status virar done.

Use o resultado

Um item por CPF, com os mesmos campos da Consulta Simples. No dashboard, dá para exportar o arquivo pronto.

O lote atende a Consulta Simples. Para volume na Consulta em Tempo Real, que não roda em lote, fale com a gente.

Integre em qualquer linguagem

Dois passos: você envia a lista e depois consulta o job. Nada além de HTTP.

cURL · 2 passosPOST /cpf/bulk → GET /cpf/bulk/{jobId}

# Passo 1: POST com array de CPFs em JSON
curl -X POST "https://api.cpfhub.io/cpf/bulk" \
  -H "x-api-key: SUA_API_KEY" \
  -H "content-type: application/json" \
  -d '{"cpfs": ["12345678909", "11144477735", "52998224725"]}'

# → 202 Accepted  { "jobId": "4a1ef25e-052c-4464-..." }

# Passo 2: polling até status "done"
curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
  -H "x-api-key: SUA_API_KEY"

RespostaGET /cpf/bulk/{jobId}

200 OK

{
  "success": true,
  "data": {
    "id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "done",
    "total_records": 3,
    "processed": 3,
    "found": 2,
    "not_found": 1,
    "skipped": 0,
    "error": null,
    "cpfs": [
      {
        "cpf": "12345678909",
        "found": true,
        "name": "Joao de Exemplo",
        "nameUpper": "JOAO DE EXEMPLO",
        "gender": "M",
        "birthDate": "15/06/1985",
        "day": 15,
        "month": 6,
        "year": 1985
      },
      {
        "cpf": "52998224725",
        "found": false,
        "name": null,
        "nameUpper": null,
        "gender": null,
        "birthDate": null,
        "day": null,
        "month": null,
        "year": null
      }
    ]
  }
}

FAQ

Perguntas frequentes

Qual o limite por job?

Até 10.000 CPFs por requisição em POST /cpf/bulk. Acima disso a API recusa com 400. Para volumes maiores, divida em vários jobs ou fale com o Corporativo.

É síncrono ou assíncrono?

Assíncrono. O POST cria o job e devolve um jobId. Faça poll em GET /cpf/bulk/{jobId} até o status done ou failed. O dashboard também acompanha o progresso.

404 consome crédito?

Não. No lote, só itens com found: true consomem crédito. CPF não encontrado ou com dígito verificador incorreto não cobra. A mesma regra vale no GET individual (só HTTP 200).

Dá para usar lote no Grátis?

Sim. O Grátis acessa os mesmos endpoints, com 50 créditos/mês. Em 0 créditos, itens do lote são skipped (sem overage no Grátis). Pro e Corporativo cobrem volumes maiores. Veja /precos.

Quais formatos o dashboard aceita?

CSV e TXT. O separador (ponto e vírgula ou vírgula), o cabeçalho e a coluna de CPF são detectados automaticamente. Também dá para colar a lista direto num campo de texto. XLSX não é aceito: exporte como CSV antes de enviar.

O que significa cada status do job?

processing: ainda rodando, e a consulta ao job já devolve o progresso e os registros prontos. done: terminou, com o resultado completo. failed: algo travou. Um job parado há mais de 10 minutos é marcado como failed automaticamente, em vez de ficar pendurado.

O que acontece se o crédito acabar no meio do lote?

Os CPFs restantes voltam como skipped. Não são consultados nem cobrados. Você recarrega o plano e reprocessa só o que ficou de fora.

Consigo baixar o resultado em CSV?

Pelo dashboard, sim. A API devolve JSON: um item por CPF, com os mesmos campos da Consulta Simples e valores nulos quando o CPF não foi encontrado.

A Consulta em Tempo Real funciona em lote?

Não. O lote atende só a Consulta Simples. A Consulta em Tempo Real é individual, uma chamada por CPF em POST /cpf/realtime. Para volume nela, fale com a gente pelo WhatsApp ou em contato@cpfhub.io.

Ainda tem dúvidas?

Entre em Contato

Confira a base
inteira de uma vez.

Até 10.000 CPFs por job, pela API ou por upload no dashboard. Você paga só pelos que forem encontrados.

Começar grátis Falar com o time

Acesso imediato à API Key e à documentação.

Sua base inteira,conferida de uma vez.