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.
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:
POST /cpf/bulkenvia a lista e responde na hora com umjobId.GET /cpf/bulk/{jobId}devolve o progresso e os resultados. Repita atéstatusser"done"ou"failed".
Endpoint
https:/ / api.cpfhub.io/ cpf/ bulkParâmetros
| Onde | Nome | Obrigatório | Descrição |
|---|---|---|---|
| Header | x-api-key | Sim | Sua API Key. Veja Autenticação. |
| Header | Content-Type | Sim | application/json |
| Body | cpfs | Sim | string[] 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. |
| Body | fileName | Não | Rótulo livre. Volta como file_name no status. |
| Body | format | Não | Rótulo livre do formato de origem (ex.: "csv"). Volta como format. |
O que acontece no envio
| Etapa | Efeito |
|---|---|
| Normalização | Remove a formatação. CPFs sem 11 dígitos ou com dígito verificador errado vão para invalid e não são cobrados. |
| Duplicados | Removidos. Cada CPF é consultado e cobrado uma vez. Não entram em totalRecords nem em invalid. |
| Limite por minuto | Cada envio conta uma requisição no limite da Consulta Simples (30 por minuto no padrão). |
| Saldo | Sem 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
{
"success": true,
"data": {
"jobId": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
"status": "processing",
"totalRecords": 3,
"invalid": 0
}
}| Campo | Tipo | Descrição |
|---|---|---|
data.jobId | string | ID do lote. Guarde para consultar o status. |
data.status | string | Sempre "processing" |
data.totalRecords | number | CPFs válidos e únicos que serão consultados |
data.invalid | number | Itens descartados (formato, dígito verificador ou não string) |
O envio responde em camelCase. O status responde em snake_case.
Status e resultados
https:/ / 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
cpfsinteiro (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
5xxou erro de rede, tente de novo no próximo ciclo. OGETé 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
{
"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
}
]
}
}| Campo | Descrição |
|---|---|
data.id | ID do lote (o jobId do envio) |
data.status | "processing", "done" ou "failed" |
data.total_records | CPFs válidos e únicos no lote |
data.processed | CPFs já processados (inclui skipped) |
data.found | Encontrados. Cada um consome 1 crédito no padrão (custo do seu plano no dashboard) |
data.not_found | Não encontrados. Não consomem crédito. |
data.skipped | Não consultados porque o saldo acabou durante o lote (sem overage). Não consomem crédito. |
data.error | Motivo da falha quando status é "failed" |
data.file_name, data.format | Rótulos enviados no POST |
data.created_at, data.updated_at | Datas 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
| Status | Quando acontece | O que fazer |
|---|---|---|
400 | cpfs ausente, vazio, não é array ou tem mais de 10.000 itens | Corrija o body. |
401 | API Key ausente, inválida ou inativa (error string) | Confira o header x-api-key. |
403 | Sem 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. |
404 | jobId não existe ou foi criado com outra API Key | Confira o jobId e a chave. |
422 | Nenhum CPF válido na lista | Corrija a lista. |
429 | Limite por minuto excedido (só no POST) | Espere os segundos do header Retry-After. |
500, 503 | Falha passageira no POST. Nenhum lote foi criado. | Tente de novo. Reporte se persistir. |
503 | Falha 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ção | Como identificar | O que fazer |
|---|---|---|
| Em processamento | status: "processing" | Continue o polling. cpfs já traz resultados parciais. |
| Concluído | "done" e skipped: 0 | Use cpfs. |
| Concluído com pulados | "done" e skipped > 0 | Saldo 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:
error | Significado |
|---|---|
"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
POSTaceito cria um lote novo e cobra os encontrados. Se a conexão cair semjobId, confira o dashboard ouGET /quotaantes de reenviar. Com resposta de erro, nenhum lote foi criado. - Crédito: só
found: trueé cobrado. Inválidos, repetidos, não encontrados eskippednão. - Exportação CSV: só no dashboard, com
CPF,Nome,NascimentoeEncontrado(sem gênero).
Atualizado em 4 de outubro de 2026