Consulta de CPF em Lote

Envia um array de CPFs para processamento em lote. Use esse endpoint quando precisar consultar muitos CPFs de uma vez, em vez de chamar GET /cpf/{cpf} individualmente. Se preferir uma interface sem código, o dashboard (app.cpfhub.io/lote) faz upload de CSV/TXT e exportação do resultado automaticamente.

ℹ

Processamento assíncrono

O envio retorna imediatamente com um jobId. O processamento acontece em segundo plano. Use o endpoint de status para acompanhar o progresso e obter os resultados.

Endpoint

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

Autenticação

Envie sua API Key no header x-api-key, a mesma usada em todos os endpoints. Veja Autenticação.

Parâmetros

Headers

Header	Obrigatório	Descrição
`x-api-key`	Sim	Sua API Key do CPFHub.io
`Content-Type`	Sim	`application/json`

Body

Campo	Tipo	Obrigatório	Descrição
`cpfs`	`string[]`	Sim	Array de CPFs a consultar, com ou sem formatação. Não pode ser vazio. Máximo de 10.000 itens.

⚠

Limite de 10.000 CPFs por requisição

Lotes acima de 10.000 CPFs são recusados com 400 Bad Request. Para volumes maiores, divida em múltiplas chamadas a POST /cpf/bulk.

Exemplos de requisição

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

Resposta de sucesso

HTTP 202 Accepted

O lote foi aceito e enfileirado para processamento. CPFs com formato inválido são descartados antes da contagem de totalRecords.

JSON

{
  "success": true,
  "data": {
    "jobId": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "processing",
    "totalRecords": 3,
    "invalid": 0
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	`true` se o lote foi aceito
`data.jobId`	`string`	ID do job. Use para consultar o status e obter os resultados.
`data.status`	`string`	Status inicial, sempre `"processing"`
`data.totalRecords`	`number`	CPFs válidos aceitos para processamento
`data.invalid`	`number`	CPFs descartados por formato inválido (não entram em `totalRecords`)

Consultando o status e os resultados

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

Envie o mesmo header x-api-key. Faça polling até data.status ser "done" ou "failed", com intervalos de alguns segundos entre as chamadas. O campo id na resposta corresponde ao jobId retornado pelo POST.

curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
-H "x-api-key: SUA_API_KEY"

HTTP 200 OK

JSON

{
  "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": "11144477735",
        "found": true,
        "name": "Ana de Exemplo",
        "nameUpper": "ANA DE EXEMPLO",
        "gender": "F",
        "birthDate": "01/01/1990",
        "day": 1,
        "month": 1,
        "year": 1990
      },
      {
        "cpf": "10415045606",
        "found": true,
        "name": "João de Exemplo",
        "nameUpper": "JOÃO DE EXEMPLO",
        "gender": "M",
        "birthDate": "15/06/1985",
        "day": 15,
        "month": 6,
        "year": 1985
      },
      {
        "cpf": "00000000000",
        "found": false,
        "name": null,
        "nameUpper": null,
        "gender": null,
        "birthDate": null,
        "day": null,
        "month": null,
        "year": null
      }
    ]
  }
}

Campos da resposta

Campo	Tipo	Descrição
`data.status`	`"processing"` \| `"done"` \| `"failed"`	Estado atual do job
`data.total_records`	`number`	CPFs válidos no lote
`data.processed`	`number`	CPFs já processados
`data.found`	`number`	CPFs encontrados na base (consomem 1 crédito cada)
`data.not_found`	`number`	CPFs não encontrados (não consomem crédito)
`data.skipped`	`number`	CPFs não processados por falta de créditos. Se `skipped > 0`, recarregue seus créditos e envie um novo lote com esses CPFs.
`data.error`	`string \| null`	Mensagem de erro, presente quando `status` é `"failed"`
`data.cpfs`	`array`	Resultado individual de cada CPF processado

ℹ

Resultados parciais durante o processamento

Enquanto status é "processing", data.cpfs contém apenas os CPFs já processados até o momento. O array cresce a cada nova chamada ao endpoint de status. CPFs com skipped não aparecem em data.cpfs.

Campos de `data.cpfs[]`

Campo	Tipo	Descrição
`cpf`	`string`	CPF sem formatação, com 11 dígitos.
`found`	`boolean`	`true` se o CPF foi encontrado na base
`name`	`string \| null`	Nome completo, `null` se não encontrado
`nameUpper`	`string \| null`	Nome em caixa alta, `null` se não encontrado
`gender`	`"M"` \| `"F"` \| `null`	Gênero, `null` se não encontrado
`birthDate`	`string \| null`	Data de nascimento no formato `DD/MM/AAAA`, `null` se não encontrado
`day`, `month`, `year`	`number \| null`	Componentes numéricos da data de nascimento, `null` se não encontrado

✦

CPFs inválidos e não encontrados não consomem créditos

Apenas CPFs com found: true consomem 1 crédito do seu plano, igual ao endpoint de consulta individual.

Exportando os resultados

A API retorna os resultados em JSON via data.cpfs[]. A exportação em CSV está disponível apenas no dashboard (app.cpfhub.io/lote).

Códigos de status HTTP

Status	Descrição
`202 Accepted`	Lote aceito e enfileirado para processamento
`200 OK`	Status do job retornado com sucesso (no `GET /cpf/bulk/{jobId}`)
`400 Bad Request`	Campo `cpfs` ausente, não é array, está vazio, ou excede o limite de 10.000 CPFs
`401 Unauthorized`	API Key ausente ou inválida
`404 Not Found`	`jobId` não existe ou não pertence à sua conta
`422 Unprocessable Entity`	Nenhum CPF com formato válido na lista enviada
`429 Too Many Requests`	Limite de taxa excedido
`500 Internal Server Error`	Erro interno. Reporte se persistir.

⚠

Formato de erro diferente do endpoint individual

Erros de autenticação (401) retornam error como string simples. Os demais erros (400, 404, 422) retornam error como objeto com campo message. Esse comportamento difere do padrão { code, message } usado em GET /cpf/{cpf}. Trate os dois formatos ao integrar.

JSON

// 401 - API Key ausente ou inválida
{ "success": false, "error": "API Key inválida" }

// 400 - body inválido
{ "success": false, "data": null, "error": { "message": "Campo 'cpfs' deve ser um array não vazio." } }

// 400 - limite excedido
{ "success": false, "data": null, "error": { "message": "Limite de 10000 CPFs por lote excedido." } }

// 404 - jobId não encontrado
{ "success": false, "data": null, "error": { "message": "Lote não encontrado." } }

// 422 - nenhum CPF com formato válido
{ "success": false, "data": null, "error": { "message": "Nenhum CPF válido na lista enviada." } }

Para a lista completa de códigos de erro do endpoint individual, veja Códigos de Erro.

Atualizado em 16 de junho de 2026

Consulta de CPF em Lote

Endpoint

Autenticação

Parâmetros

Headers

Body

Exemplos de requisição

Resposta de sucesso

Consultando o status e os resultados

Campos da resposta

Campos de data.cpfs[]

Exportando os resultados

Códigos de status HTTP

Campos de `data.cpfs[]`