NewFacial identity verification

Bulk CPF Verification: Checking Thousands of Brazilian IDs at Once

Verify up to 10,000 Brazilian CPFs per request with an asynchronous bulk API: how to submit a batch, poll for results, handle credits and stay LGPD-safe.

Lucas Vieira
Lucas Vieira
··6 min read
Bulk CPF Verification: Checking Thousands of Brazilian IDs at Once

Introduction

To verify thousands of Brazilian CPFs (Brazil's individual taxpayer registry number) at once, send them in a single POST /cpf/bulk request with a JSON array of up to 10,000 numbers. The API answers right away with a job ID, processes the batch in the background, and you poll for the results. Each CPF found comes back with name, gender and date of birth, and CPFs not found do not use credits.

Bulk verification is the right tool for cleaning an existing customer base, migrating records from another system or re-checking a portfolio before a campaign. This guide shows the full flow, the credit rules and the limits.


When bulk beats a loop

Calling GET /cpf/{cpf} in a loop works for a few hundred records, but it runs into the per-minute request limit of each API key and makes you handle retries one by one. The batch endpoint was built for volume:

Simple Lookup in a loopBulk endpoint
RequestsOne per CPFOne per batch of up to 10,000
Rate limitEvery call countsEach batch submission counts once
Duplicates and invalid numbersYou filter themDiscarded automatically, not charged
ResultsImmediate, per callAsynchronous, by polling
Best forSignup and checkoutBase cleaning, migrations, periodic re-checks

Step 1: submit the batch

The body is JSON with a cpfs array. File uploads are not accepted by the API, so read your file and send the numbers:

curl --max-time 30 -X POST https://api.cpfhub.io/cpf/bulk \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cpfs": ["00000000000"], "fileName": "customers-2026-12"}'

The API answers 202 Accepted, the standard HTTP status for work accepted but not yet finished (RFC 9110):

{
  "success": true,
  "data": { "jobId": "...", "status": "processing", "totalRecords": 1, "invalid": 0 }
}

Replace the placeholder with your customers' CPFs. Before queueing, the API removes invalid numbers (counted in invalid) and looks up repeated CPFs only once. A batch with no valid CPF returns 422.

The submission is not idempotent. If the request times out, check your job list before sending it again, or you may create a second batch.


Step 2: poll for results

Call GET /cpf/bulk/{jobId} until status is done or failed. Partial results appear while the job runs, and polling does not use credits. Here is a Python version that reads the key from the CPFHUB_API_KEY environment variable and sets a timeout on every call:

import os
import time
import requests

API = "https://api.cpfhub.io"
HEADERS = {"x-api-key": os.environ["CPFHUB_API_KEY"]}


def submit(cpfs: list[str]) -> str:
    r = requests.post(f"{API}/cpf/bulk", json={"cpfs": cpfs}, headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()["data"]["jobId"]


def wait(job_id: str, every: int = 10) -> dict:
    while True:
        r = requests.get(f"{API}/cpf/bulk/{job_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        job = r.json()["data"]
        if job["status"] in ("done", "failed"):
            return job
        time.sleep(every)


job = wait(submit(["00000000000"]))
print(job["found"], job["not_found"], job["skipped"])
for item in job["cpfs"]:
    if item["found"]:
        print(item["cpf"], item["name"], item["birthDate"])

Two details trip people up. The poll response uses id, not jobId, and its counters are in snake case (total_records, not_found). Each item in cpfs has cpf, found, name, nameUpper, gender, birthDate, day, month and year, with null fields when found is false. Only the account that created the job can read it. Full field list in the batch reference.


How credits work in bulk

  • Only CPFs found use credits. Not found, invalid and duplicate numbers are free.
  • Plans without overage, including the free plan, need balance for the whole batch up front: the number of valid CPFs times the Simple Lookup cost. Without it, the API returns 403 and the batch is not created.
  • skipped appears only if the balance runs out while the job is running, for example because other lookups ran in parallel.
  • You can check your balance at any time with GET /quota, which never uses credits (quota reference).

Plans and volumes are on the pricing page.


Limits to plan around

  • 10,000 CPFs per batch. Split larger files into several batches.
  • Pending batches per account are capped. Above the cap the API returns 429 with a Retry-After header, as defined in RFC 9110. Wait and submit the next one.
  • The Real-Time Lookup is not available in bulk. Registration status, year of death and the Receita Federal proof come one CPF at a time from the Real-Time Lookup.
  • JSON only from the API. If you prefer a spreadsheet, the dashboard's batch screen accepts CSV or TXT files (not XLSX) up to 10,000 CPFs and lets you download the results as CSV.

Bulk verification and the LGPD

Volume does not change the rules. Under the LGPD (Brazil's data protection law, Law 13,709/2018), every lookup needs a legal basis and a defined purpose. Bulk verification fits when you check CPFs of your own customers, employees or applicants, who gave you the number for a reason you told them about.

It does not fit building lists of people from CPFs you collected elsewhere. Keep the results only as long as the purpose requires, and see the security and compliance page for how CPFHub.io handles data. When in doubt about your legal basis, ask Brazilian counsel.


Frequently asked questions

How many CPFs can I verify per request?

Up to 10,000 per batch. Invalid numbers and duplicates are removed before processing and are not charged.

Can I upload a CSV file to the API?

No. The API takes a JSON array in the cpfs field. The dashboard accepts CSV and TXT files and converts them for you.

What happens if my balance does not cover the batch?

On plans without overage, the API returns 403 and does not create the batch. Reduce the batch size or move to a plan with more credits, then send it again.

Can I verify CNPJs in bulk too?

Yes. The bulk CNPJ lookup works the same way with a cnpjs array of up to 10,000 numbers.


Read also

Conclusion

Bulk CPF verification is one JSON request per 10,000 numbers, a job ID and a polling loop. Duplicates and invalid numbers are filtered for you, only CPFs found use credits and the same LGPD rules apply as for a single lookup.

See the bulk CPF lookup page and start with 50 free credits and no credit card at cpfhub.io.

CPFHub.io

Ready to integrate the API?

50 free credits to test now. No credit card. Instant access to the documentation.

WhatsApp