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 (Grátis / pago sem overage). Planos com overage ativo não pulam por franquia. 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 do lote

Erros de autenticação (401) retornam error como string simples — o mesmo formato de GET /cpf/{cpf}. Os demais erros (400, 404, 422) retornam error como objeto com campo message.

JSON

// 401 - API Key ausente
{ "success": false, "error": "API Key não fornecida" }

// 401 - API Key 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 5 de setembro 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[]`