# Consulta de CPF em lote: até 10.000 por job | CPFHub.io

> Confira sua base inteira de uma vez. Até 10.000 CPFs por job assíncrono, pela API ou por upload de CSV no dashboard. Você paga só pelos CPFs encontrados.

**URL:** https://www.cpfhub.io/consulta-cpf-em-lote

---

# Sua base inteira,  
conferida de uma vez.

Envie até 10.000 CPFs em um único lote e acompanhe o processamento. Só os CPFs encontrados consomem crédito.

[Começar grátis](https://app.cpfhub.io/auth/register) [Ver documentação](https://www.cpfhub.io/documentacao/referencia/lote) 

50 créditos grátis por mês, sem cartão de crédito.

## Dez mil consultas. Uma requisição.

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

### Até 10.000 CPFs por lote

Você envia a lista inteira em uma requisição e recebe o jobId na hora, sem disparar dez mil chamadas nem sobrecarregar o seu servidor.

### Resultado parcial durante o processamento

O lote não é uma caixa preta. A cada consulta ao status, você vê quantos CPFs foram processados, quantos foram encontrados e os registros já prontos.

### Os mesmos campos da Consulta Simples

Cada CPF encontrado volta com nome, gênero e data de nascimento, no mesmo formato da consulta individual. CPF não encontrado volta com os campos em null.

`name` `nameUpper` `gender` `birthDate` `day` `month` `year` 

### Sem código, se você preferir

O painel aceita arquivos CSV e TXT, identifica sozinho o separador e a coluna de CPF e exporta o resultado. Você também pode colar a lista em um campo de texto.

## Envie a lista. Acompanhe o lote.

O processamento é assíncrono: a sua requisição não fica esperando dez mil consultas terminarem.

1.  01
    
    ### Envie a lista
    
    Um POST com o array de CPFs. A resposta chega na hora com o jobId, e o processamento continua em segundo plano.
    
2.  02
    
    ### Acompanhe o lote
    
    Consulte o jobId quando quiser. Cada consulta traz o progresso e os registros já concluídos, até o status mudar para done.
    
3.  03
    
    ### Use o resultado
    
    Um item por CPF, com os mesmos campos da Consulta Simples. No painel, você exporta o arquivo pronto.
    

O lote usa a [Consulta Simples](https://www.cpfhub.io/api-consulta-cpf) . A [Consulta em Tempo Real](https://www.cpfhub.io/consulta-cpf-receita-federal)  não roda em lote. Para volume nela, fale com o nosso time.

## Integre em qualquer linguagem

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

cURLPOST /cpf/bulk → GET /cpf/bulk/{jobId}

```bash
# Passo 1: envie a lista de CPFs
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: aguarde o 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

```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": "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
      }
    ]
  }
}
```

[Pegue sua chave grátis](https://app.cpfhub.io/auth/register) [Ver documentação](https://www.cpfhub.io/documentacao) 

50 créditos grátis por mês, sem cartão.

## Você sabe onde o lote está.

Três status possíveis e cinco contadores. Você sabe se o lote está rodando, se terminou ou se parou.

### processing

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

### done

O lote terminou. A resposta traz o resultado completo, item por item.

### failed

O lote parou. Um lote sem progresso por mais de 10 minutos é marcado automaticamente, em vez de ficar pendente para sempre.

### Contadores do lote

`total_records` 

Quantos CPFs válidos entraram no lote.

`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 porque o saldo acabou durante o processamento.

## 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 ou sem data de nascimento. Envie a base inteira e padronize tudo 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 que não existem na base e cadastros com nome ou data de nascimento diferentes do informado 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 nome e a data de nascimento retornados.

### 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

Recebeu a carteira de clientes de outra empresa? O lote mostra em poucas horas quantos cadastros estão corretos.

## Você paga pelos CPFs que existem.

Em uma base antiga, muitos registros não existem mais. Aqui, CPF não encontrado não consome crédito, então base desatualizada não vira fatura maior.

1 crédito

por CPF encontrado, como na Consulta Simples

R$ 0

por CPF não encontrado ou com formato ou dígito verificador incorreto

10.000

CPFs por lote, quantos lotes você precisar

Em planos sem excedente, o lote só é aceito se houver saldo para todos os CPFs válidos. Se o saldo acabar durante o processamento, os CPFs restantes voltam como `skipped` , sem consulta e sem cobrança.

[Ver planos](https://www.cpfhub.io/precos) 

## Perguntas frequentes

Atendimento automatizado 24 horas

Ainda tem dúvidas?

Fale com a gente pelo WhatsApp.

[Falar com o time](https://api.whatsapp.com/send/?phone=551132300861&text=Ol%C3%A1!%20Preciso%20consultar%20CPFs%20em%20lote%20e%20gostaria%20de%20entender%20como%20funciona%20o%20processamento%20ass%C3%ADncrono%20da%20CPFHub.io.&type=phone_number&app_absent=0) 

Qual o limite por lote?

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 lotes ou fale com o nosso time sobre o plano Corporativo.

O processamento é síncrono ou assíncrono?

Assíncrono. O POST cria o lote e devolve um jobId. Consulte GET /cpf/bulk/{jobId} até o status mudar para done ou failed. O painel também acompanha o progresso.

CPF não encontrado consome crédito?

Não. No lote, só itens com found: true consomem crédito. CPF não encontrado ou com formato ou dígito verificador incorreto não é cobrado. A mesma regra vale na consulta individual.

Posso usar o lote no plano Grátis?

Sim. O plano Grátis acessa os mesmos endpoints, com 50 créditos por mês. Em planos sem excedente, como o Grátis, o lote só é aceito se houver saldo para todos os CPFs válidos. Sem saldo suficiente, a API responde 403 e nada é cobrado. Veja /precos.

Quais formatos o painel aceita?

CSV e TXT. O separador (ponto e vírgula ou vírgula), o cabeçalho e a coluna de CPF são identificados automaticamente. Você também pode colar a lista em um campo de texto. XLSX não é aceito: exporte como CSV antes de enviar.

O que significa cada status do lote?

processing: o lote está rodando, e a consulta já devolve o progresso e os registros prontos. done: terminou, com o resultado completo. failed: o lote parou. Um lote sem progresso por mais de 10 minutos é marcado como failed automaticamente.

O que acontece se o saldo acabar durante o lote?

Os CPFs restantes voltam como skipped. Não são consultados nem cobrados. Você recarrega o saldo e envia um novo lote só com os CPFs que ficaram de fora.

Consigo baixar o resultado em CSV?

Pelo painel, sim. A API devolve JSON: um item por CPF, com os mesmos campos da Consulta Simples e valores null 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 o nosso time pelo WhatsApp ou em contato@cpfhub.io.

## Confira a base  
inteira de uma vez.

[Começar grátis](https://app.cpfhub.io/auth/register) [Falar com o time](https://api.whatsapp.com/send/?phone=551132300861&text=Ol%C3%A1!%20Preciso%20consultar%20CPFs%20em%20lote%20e%20gostaria%20de%20entender%20como%20funciona%20o%20processamento%20ass%C3%ADncrono%20da%20CPFHub.io.&type=phone_number&app_absent=0) 

*   50 créditos grátis por mês
*   Sem cartão de crédito
*   Atendimento 24h no WhatsApp