Batch Lookup

Your whole database,
checked at once.

Send up to 10,000 CPFs (Brazil's individual taxpayer IDs) in a single job and track its progress. You pay only for the ones found, and nothing for the ones that don't exist.

Start for free Talk about volume

Same key and same credit as the Simple Lookup. From the dashboard or through the API.

What you get

Ten thousand lookups. One request.

The work of orchestrating the queue, parallelism and retries stays on our side.

One job, up to 10,000 CPFs

You send the whole list in one request and get a jobId right away. No firing off ten thousand calls and hoping your server holds up.

Partial results while it runs

The job is not a black box. Each time you check the status, you see how many were processed, how many were found, and the records completed so far.

Billed only for what is found

Each CPF found uses 1 credit. A CPF that is not found, or has an incorrect format or check digit, uses nothing. A messy database does not turn into an inflated invoice.

No code, if you prefer

The dashboard accepts CSV or TXT files, detects the separator and the CPF column on its own, and exports the result. You can also paste the list straight into a text field.

Tracking

You always know where the job is.

Three possible states and five counters. No guessing whether it got stuck or is still running.

processing

The job is running. Checking the status returns its progress and the records already completed.

done

Finished. The response includes the full result, item by item.

failed

Something got stuck. A job that has been stalled for more than 10 minutes is flagged automatically instead of hanging forever.

Job counters

total_records

How many valid CPFs entered the job.

processed

How many have already been looked up.

found

How many exist in the database. This is what you pay for.

not_found

How many have no record. They are not charged.

skipped

How many were left out for lack of credit.

How billing works

You pay for the CPFs
that exist.

In an old database, a good share of the records will no longer exist. Many services charge for each of those attempts anyway. Here, an attempt with no result does not count toward your bill.

1 credit

per CPF found, same as 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 job, as many jobs as you need

If your credits run out in the middle of a batch, the remaining CPFs come back as skipped. They are neither looked up nor charged, and you can reprocess them whenever you like.

See plans

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 and missing dates of birth. Run the whole database through and normalize 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.

Enrich before a campaign

With the correct name and date of birth on hand, segmentation and personalization actually work.

Periodic record audit

Run the batch every month and track how many records in your database no longer match the official data.

Portfolio reconciliation

Before billing, renewing or paying out commissions, confirm that the holders in your portfolio are who the records say they are.

Acquisition due diligence

You bought a database along with the company. The batch tells you within hours what percentage of it is usable.

How it works

Send it and track it. That's all.

The job is asynchronous, so your request is not left hanging while ten thousand lookups finish.

Send the list

A POST with the array of CPFs. The response comes back right away with the jobId, without holding your request while it processes.

Track the job

Check the jobId whenever you like. Each check returns the progress and the records already completed, until the status becomes done.

Use the result

One item per CPF, with the same fields as the Simple Lookup. In the dashboard, you can export the finished file.

Batch serves the Simple Lookup. For volume on the Real-Time Lookup, which does not run in batches, talk to us.

Integrate in any language

Two steps: send the list, then check the job. Nothing beyond HTTP.

cURL · 2 stepsPOST /cpf/bulk → GET /cpf/bulk/{jobId}

# Step 1: POST an array of CPFs as JSON
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: poll until the status is "done"
curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
  -H "x-api-key: YOUR_API_KEY"

ResponseGET /cpf/bulk/{jobId}

200 OK

{
  "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
      }
    ]
  }
}

FAQ

Frequently asked questions

What is the limit per job?

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 jobs or talk to us about Enterprise.

Is it synchronous or asynchronous?

Asynchronous. The POST creates the job and returns a jobId. Poll GET /cpf/bulk/{jobId} until the status is done or failed. The dashboard also tracks progress.

Does a 404 use a credit?

No. In batch, only items with found: true use a credit. A CPF that is not found or has an incorrect check digit is not charged. The same rule applies to the single GET (HTTP 200 only).

Can I use batch on the Free plan?

Yes. The Free plan reaches the same endpoints, with 50 credits/month. At 0 credits, batch items are skipped (no overage on Free). Pro and Enterprise cover larger volumes. 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 straight into a text field. XLSX is not accepted: export it as CSV before sending.

What does each job status mean?

processing: still running, and checking the job already returns progress and the finished records. done: finished, with the full result. failed: something got stuck. A job that has been stalled for more than 10 minutes is marked as failed automatically instead of hanging.

What happens if credits run out in the middle of a batch?

The remaining CPFs come back as skipped. They are not looked up and not charged. You top up the plan and reprocess only what was 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 us on WhatsApp or at contato@cpfhub.io.

Still have questions?

Get in touch

Check your whole
database at once.

Up to 10,000 CPFs per job, through the API or by upload in the dashboard. You pay only for the ones that are found.

Start for free Talk to our team

Instant access to your API key and the documentation.

Your whole database,checked at once.