Batch Lookup

Send a list of up to 10,000 CPFs (Brazil's individual taxpayer ID numbers) and get the name, gender and date of birth for each one, processed in the background. It costs 1 credit per CPF found.

Not the one you need? Compare the lookups. If you prefer no code, the dashboard accepts CSV/TXT files or pasted CPFs and exports the result as CSV.

Two-step flow:

1. POST /cpf/bulk sends the list and responds immediately with a jobId.
2. GET /cpf/bulk/{jobId} returns the progress and the results. Repeat until status is "done" or "failed".

Endpoint

Parameters

What happens on submission

More than 10,000 CPFs: split them into chunks and send one POST for each.

Example

Check the status before reading data: on error, the response has no jobId.

curl -X POST "https://api.cpfhub.io/cpf/bulk" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cpfs": ["12345678909", "11144477735", "52998224725"]
  }'

Response

HTTP 202 Accepted

{
  "success": true,
  "data": {
    "jobId": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "processing",
    "totalRecords": 3,
    "invalid": 0
  }
}

The submission responds in camelCase. The status responds in snake_case.

Status and results

Use the same API key as the submission. It does not use credits, does not count toward the per-minute limit and works with a zero balance.

Polling:

• Start at every 5 s and increase up to 30 s on large batches. Each call returns the whole cpfs array (up to ~2 MB for 10,000 CPFs).
• Set a maximum deadline in your client (for example, 30 min). The batch time depends on how many CPFs you submitted, and each lookup stays in the same range as the Simple Lookup (~150 ms).
• On a 5xx or a network error, try again on the next cycle. The GET is safe to repeat.

curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
  -H "x-api-key: $CPFHUB_API_KEY"

HTTP 200 OK

{
  "success": true,
  "data": {
    "id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "done",
    "file_name": null,
    "format": null,
    "total_records": 2,
    "processed": 2,
    "found": 1,
    "not_found": 1,
    "skipped": 0,
    "error": null,
    "created_at": "2026-10-02T14:15:16.000Z",
    "updated_at": "2026-10-02T14:15:18.000Z",
    "cpfs": [
      {
        "cpf": "12345678909",
        "found": true,
        "name": "Fulano de Tal",
        "nameUpper": "FULANO DE TAL",
        "gender": "M",
        "birthDate": "15/06/1990",
        "day": 15,
        "month": 6,
        "year": 1990
      },
      {
        "cpf": "52998224725",
        "found": false,
        "name": null,
        "nameUpper": null,
        "gender": null,
        "birthDate": null,
        "day": null,
        "month": null,
        "year": null
      }
    ]
  }
}

While the status is "processing", the counters update every 50 CPFs and may lag behind cpfs.

Errors

The API only responds in Portuguese. Error messages are shown as returned, with the translation in parentheses the first time.

Error format, retries and how to test without spending credits: Error Codes. Per-minute limit and credits: Usage Limits.

Details

Batch states

Values of error when the batch fails:

With overage, no CPF is skipped: all of them are looked up and the overage is billed.

Matching the results to your list

cpfs comes in processing order and does not include skipped or unprocessed items. Normalize your list to 11 digits and match on the cpf field. The ones that are missing are the ones to resend (this includes invalid ones, which cost nothing).

const normalize = (cpf: string) => cpf.replace(/\D/g, '')

const results = new Map(job.cpfs.map((item) => [item.cpf, item]))

for (const original of myCpfs) {
  const result = results.get(normalize(original))
  console.log(original, result ? (result.found ? result.name : 'not found') : 'no result')
}

// CPFs to resend in a new batch (if the batch failed or had skipped items)
const missing = [...new Set(myCpfs.map(normalize))].filter((cpf) => !results.has(cpf))

More

• Non-idempotent submission: each accepted POST creates a new batch and charges the ones found. If the connection drops without a jobId, check the dashboard or GET /quota before resending. If you got an error response, no batch was created.
• Credits: only found: true is charged. Invalid, duplicate, not found and skipped items are not.
• CSV export: only in the dashboard, with the columns CPF, Nome (name), Nascimento (date of birth) and Encontrado (found), without gender.

Updated on October 4, 2026