CPFHub.io

Consulta em Lote

Envie uma lista de até 10.000 CPFs e receba, para cada um, nome, gênero e data de nascimento, processados em segundo plano. Custa 1 crédito por CPF encontrado.

Usando Cursor, Lovable, v0 ou outra IA? Copie o prompt da consulta em lote e cole no seu assistente.

Abrir no Cursor

Não é essa? Compare as consultas. Sem código, o dashboard aceita CSV/TXT ou CPFs colados e exporta o resultado em CSV.

Fluxo em dois passos:

  1. POST /cpf/bulk envia a lista e responde na hora com um jobId.
  2. GET /cpf/bulk/{jobId} devolve o progresso e os resultados. Repita até status ser "done" ou "failed".

Endpoint

POSThttps://api.cpfhub.io/cpf/bulk

Parâmetros

OndeNomeObrigatórioDescrição
Headerx-api-keySimSua API Key. Veja Autenticação.
HeaderContent-TypeSimapplication/json
BodycpfsSimstring[] de CPFs, com ou sem formatação. Não vazio, máximo 10.000. Itens que não são string contam como inválidos.
BodyfileNameNãoRótulo livre. Volta como file_name no status.
BodyformatNãoRótulo livre do formato de origem (ex.: "csv"). Volta como format.

O que acontece no envio

EtapaEfeito
NormalizaçãoRemove a formatação. CPFs sem 11 dígitos ou com dígito verificador errado vão para invalid e não são cobrados.
DuplicadosRemovidos. Cada CPF é consultado e cobrado uma vez. Não entram em totalRecords nem em invalid.
Limite por minutoCada envio conta uma requisição no limite da Consulta Simples (30 por minuto no padrão).
SaldoSem overage: o saldo precisa cobrir todos os CPFs válidos (totalRecords × custo da Consulta Simples, 1 crédito no padrão). Se não cobrir, 403 e nada é cobrado.

Mais de 10.000 CPFs: divida em blocos e envie um POST para cada um.

Exemplo

Confira o status antes de ler data: em erro, a resposta não traz jobId.

curl -X POST "https://api.cpfhub.io/cpf/bulk" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cpfs": ["12345678909", "11144477735", "52998224725"]
  }'

Resposta

HTTP 202 Accepted

JSON
{
  "success": true,
  "data": {
    "jobId": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "processing",
    "totalRecords": 3,
    "invalid": 0
  }
}
CampoTipoDescrição
data.jobIdstringID do lote. Guarde para consultar o status.
data.statusstringSempre "processing"
data.totalRecordsnumberCPFs válidos e únicos que serão consultados
data.invalidnumberItens descartados (formato, dígito verificador ou não string)

O envio responde em camelCase. O status responde em snake_case.

Status e resultados

GEThttps://api.cpfhub.io/cpf/bulk/{jobId}

Use a mesma API Key do envio. Não consome crédito, não conta no limite por minuto e funciona com saldo zerado.

Polling:

  • Comece a cada 5 s e aumente até 30 s em lotes grandes. Cada chamada devolve o array cpfs inteiro (até ~2 MB em 10.000 CPFs).
  • Defina um prazo máximo no cliente (ex.: 30 min). O tempo do lote depende de quantos CPFs estão no envio.
  • Em 5xx ou erro de rede, tente de novo no próximo ciclo. O GET é seguro para repetir.
curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
  -H "x-api-key: $CPFHUB_API_KEY"

HTTP 200 OK

JSON
{
  "success": true,
  "data": {
    "id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "done",
    "file_name": null,
    "format": null,
    "total_records": 2,
    "processed": 2,
    "found": 1,
    "not_found": 1,
    "skipped": 0,
    "error": null,
    "created_at": "2026-10-02T14:15:16.000Z",
    "updated_at": "2026-10-02T14:15:18.000Z",
    "cpfs": [
      {
        "cpf": "12345678909",
        "found": true,
        "name": "Fulano de Tal",
        "nameUpper": "FULANO DE TAL",
        "gender": "M",
        "birthDate": "15/06/1990",
        "day": 15,
        "month": 6,
        "year": 1990
      },
      {
        "cpf": "52998224725",
        "found": false,
        "name": null,
        "nameUpper": null,
        "gender": null,
        "birthDate": null,
        "day": null,
        "month": null,
        "year": null
      }
    ]
  }
}
CampoDescrição
data.idID do lote (o jobId do envio)
data.status"processing", "done" ou "failed"
data.total_recordsCPFs válidos e únicos no lote
data.processedCPFs já processados (inclui skipped)
data.foundEncontrados. Cada um consome 1 crédito no padrão (custo do seu plano no dashboard)
data.not_foundNão encontrados. Não consomem crédito.
data.skippedNão consultados porque o saldo acabou durante o lote (sem overage). Não consomem crédito.
data.errorMotivo da falha quando status é "failed"
data.file_name, data.formatRótulos enviados no POST
data.created_at, data.updated_atDatas ISO 8601
data.cpfs[]Resultado de cada CPF processado: cpf (11 dígitos), found, name, nameUpper, gender, birthDate, day, month, year (null quando found é false)

Durante "processing", os contadores atualizam a cada 50 CPFs e podem ficar atrás de cpfs.

Erros

StatusQuando aconteceO que fazer
400cpfs ausente, vazio, não é array ou tem mais de 10.000 itensCorrija o body.
401API Key ausente, inválida ou inativa (error string)Confira o header x-api-key.
403Sem overage: saldo menor que o lote ou zerado (error.message: "Créditos insuficientes para o lote: N necessários."). Também conta inativa/bloqueada. Só no POST.Recarregue créditos ou reduza o lote.
404jobId não existe ou foi criado com outra API KeyConfira o jobId e a chave.
422Nenhum CPF válido na listaCorrija a lista.
429Limite por minuto excedido (só no POST)Espere os segundos do header Retry-After.
500, 503Falha passageira no POST. Nenhum lote foi criado.Tente de novo. Reporte se persistir.
503Falha passageira ao ler o lote no GET (error.code: "bulk_results_unavailable"). O lote continua existindo.Não reenvie o lote. Repita o mesmo GET com espera crescente (2 s, 4 s, 8 s).

Formato do erro, retentativas e como testar sem gastar créditos: Códigos de Erro. Limite por minuto e créditos: Limites de Uso.

Detalhes

Estados do lote

SituaçãoComo identificarO que fazer
Em processamentostatus: "processing"Continue o polling. cpfs já traz resultados parciais.
Concluído"done" e skipped: 0Use cpfs.
Concluído com pulados"done" e skipped > 0Saldo acabou durante o lote. Recarregue e reenvie só os CPFs que faltaram.
Falhou"failed"Leia error. Os encontrados em cpfs já foram cobrados. Reenvie só os que faltaram.

Valores de error quando o lote falha:

errorSignificado
"Banco de dados indisponível"Nada foi processado nem cobrado.
"Falha ao registrar validação"Falha ao salvar um resultado. O processamento parou.
"Worker interrompido (job órfão)"Processamento interrompido. Marcado assim após ~10 min sem atualização.

Com overage, nenhum CPF é pulado: todos são consultados e o excedente é cobrado.

Casando os resultados com a sua lista

cpfs vem na ordem de processamento e não inclui skipped nem não processados. Normalize sua lista para 11 dígitos e case pelo campo cpf. Os que faltarem são os que reenviar (inclui inválidos, que não custam nada).

const normalize = (cpf: string) => cpf.replace(/\D/g, '')

const results = new Map(job.cpfs.map((item) => [item.cpf, item]))

for (const original of myCpfs) {
  const result = results.get(normalize(original))
  console.log(original, result ? (result.found ? result.name : 'não encontrado') : 'sem resultado')
}

// CPFs para reenviar em um novo lote (se o lote falhou ou teve skipped)
const missing = [...new Set(myCpfs.map(normalize))].filter((cpf) => !results.has(cpf))

Mais

  • Envio não idempotente: cada POST aceito cria um lote novo e cobra os encontrados. Se a conexão cair sem jobId, confira o dashboard ou GET /quota antes de reenviar. Com resposta de erro, nenhum lote foi criado.
  • Crédito: só found: true é cobrado. Inválidos, repetidos, não encontrados e skipped não.
  • Exportação CSV: só no dashboard, com CPF, Nome, Nascimento e Encontrado (sem gênero).

Atualizado em 4 de outubro de 2026