Batch Lookup
Your whole database,
checked at once.
Send up to 10,000 CPFs (Brazil's individual taxpayer IDs) in a single batch and track the processing. Only the CPFs found use credits.
50 free credits per month, no credit card.
What you get
Ten thousand lookups. One request.
The work of orchestrating the queue, parallelism and retries stays on our side.
Up to 10,000 CPFs per batch
You send the whole list in one request and get the jobId right away, without firing ten thousand calls or overloading your server.
Partial results while it runs
The batch is not a black box. Every time you check the status, you see how many CPFs were processed, how many were found and the records already done.
The same fields as the Simple Lookup
Each CPF found comes back with name, gender and date of birth, in the same format as the single lookup. A CPF not found comes back with the fields set to null.
namenameUppergenderbirthDatedaymonthyearNo code, if you prefer
The dashboard accepts CSV and TXT files, detects the separator and the CPF column on its own and exports the result. You can also paste the list into a text field.
How it works
Send the list. Track the batch.
Processing is asynchronous: your request does not wait for ten thousand lookups to finish.
- 01
Send the list
One POST with the array of CPFs. The response comes back right away with the jobId, and processing continues in the background.
- 02
Track the batch
Check the jobId whenever you want. Each check returns the progress and the records already done, until the status changes to done.
- 03
Use the result
One item per CPF, with the same fields as the Simple Lookup. In the dashboard, you export the finished file.
Batch uses the Simple Lookup. The Real-Time Lookup does not run in batches. For volume on it, talk to our team.
Integrate in any language
Two steps: send the list, then check the batch. Nothing beyond HTTP.
# Step 1: send the list of CPFs
curl -X POST "https://api.cpfhub.io/cpf/bulk" \
-H "x-api-key: YOUR_API_KEY" \
-H "content-type: application/json" \
-d '{"cpfs": ["12345678909", "11144477735", "52998224725"]}'
# → 202 Accepted { "jobId": "4a1ef25e-052c-4464-..." }
# Step 2: wait for status "done"
curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
-H "x-api-key: YOUR_API_KEY"{
"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
}
]
}
}50 free credits per month, no credit card required.
Tracking
You always know where the batch is.
Three possible statuses and five counters. You know whether the batch is running, finished or stopped.
processing
The batch is running. Checking the status returns the progress and the records already done.
done
The batch finished. The response has the full result, item by item.
failed
The batch stopped. A batch with no progress for more than 10 minutes is flagged automatically, instead of staying pending forever.
Batch counters
total_recordsHow many valid CPFs entered the batch.
processedHow many have already been looked up.
foundHow many exist in the database. This is what you pay for.
not_foundHow many have no record. They are not charged.
skippedHow many were left out because the balance ran out during processing.
Where to use it
When the problem is the whole database.
Situations where looking up one CPF at a time would take weeks and nobody would do it.
Clean up a legacy database
An old customer file with misspelled names or missing dates of birth. Send the whole database and standardize it in one pass.
System migration
Before moving your customer records to the new system, confirm which CPFs actually exist and decide what to do with the rest.
Fraud prevention in the active base
Find CPFs that do not exist in the database and records whose name or date of birth differs from what was provided, before they turn into losses.
Periodic record audit
Run the batch every month and track how many records in your database no longer match the name and date of birth returned.
Portfolio reconciliation
Before billing, renewing or paying out commissions, confirm that the holders in your portfolio are who the records say they are.
Due diligence in mergers and acquisitions
Received another company's customer portfolio? The batch shows within a few hours how many records are correct.
How billing works
You pay for the CPFs that exist.
In an old database, many records no longer exist. Here, a CPF that is not found does not use credits, so an outdated database does not become a bigger invoice.
1 credit
per CPF found, as in the Simple Lookup
R$ 0
per CPF not found or with an incorrect format or check digit (amounts in Brazilian reais, BRL)
10,000
CPFs per batch, as many batches as you need
On plans without overage, a batch is accepted only if the balance covers every valid CPF. If the balance runs out during processing, the remaining CPFs come back as skipped, not looked up and not charged.
Frequently asked questions
What is the limit per batch?
Up to 10,000 CPFs per request on POST /cpf/bulk. Above that, the API rejects the request with 400. For larger volumes, split them into several batches or talk to our team about the Enterprise plan.
Is processing synchronous or asynchronous?
Asynchronous. The POST creates the batch and returns a jobId. Check GET /cpf/bulk/{jobId} until the status changes to done or failed. The dashboard also tracks the progress.
Does a CPF that is not found use a credit?
No. In batch, only items with found: true use a credit. A CPF that is not found or has an incorrect format or check digit is not charged. The same rule applies to the single lookup.
Can I use batch on the Free plan?
Yes. The Free plan reaches the same endpoints, with 50 credits per month. On plans without overage, such as Free, a batch is accepted only if the balance covers every valid CPF. Without enough balance, the API returns 403 and nothing is charged. See /en/pricing.
Which formats does the dashboard accept?
CSV and TXT. The separator (semicolon or comma), the header and the CPF column are detected automatically. You can also paste the list into a text field. XLSX is not accepted: export it as CSV before sending.
What does each batch status mean?
processing: the batch is running, and checking it already returns the progress and the finished records. done: finished, with the full result. failed: the batch stopped. A batch with no progress for more than 10 minutes is flagged as failed automatically.
What happens if the balance runs out during a batch?
The remaining CPFs come back as skipped. They are not looked up and not charged. You top up the balance and send a new batch with only the CPFs that were left out.
Can I download the result as CSV?
From the dashboard, yes. The API returns JSON: one item per CPF, with the same fields as the Simple Lookup and null values when the CPF was not found.
Does the Real-Time Lookup work in batch?
No. Batch covers only the Simple Lookup. The Real-Time Lookup is individual, one call per CPF on POST /cpf/realtime. For volume on it, talk to our team on WhatsApp or at contato@cpfhub.io.
Check your whole
database at once.
- 50 free credits per month
- No credit card
- 24h assistance on WhatsApp