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 loop | Bulk endpoint | |
|---|---|---|
| Requests | One per CPF | One per batch of up to 10,000 |
| Rate limit | Every call counts | Each batch submission counts once |
| Duplicates and invalid numbers | You filter them | Discarded automatically, not charged |
| Results | Immediate, per call | Asynchronous, by polling |
| Best for | Signup and checkout | Base 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
403and the batch is not created. skippedappears 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-Afterheader, 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
- How to Use a CPF Lookup API in Python
- CPF Registration Status Explained: Regular, Suspended, Cancelled
- LGPD for Foreign Companies Processing Brazilian Personal Data
- How to Verify a Brazilian CPF Number
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.




