CNPJ Batch Lookup

Send a list of up to 10,000 CNPJs and get, for each one, the same record as the CNPJ Lookup, processed in the background. It costs 1 credit per CNPJ found.

Without code, the dashboard accepts a list of CNPJs and shows the result for each one.

Two-step flow:

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

Endpoint

Parameters

What happens on submission

More than 10,000 CNPJs: split them into chunks and send one POST for each, waiting for earlier batches if you get a 429.

Example

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

curl -X POST "https://api.cpfhub.io/cnpj/bulk" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cnpjs": ["11222333000181", "12.ABC.345/01DE-35"]
  }'

Response

HTTP 202 Accepted

{
  "success": true,
  "data": {
    "jobId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "status": "processing",
    "totalRecords": 2,
    "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 uses no credit and works with a zero balance.

Polling:

• Start every 5 s and increase up to 30 s for large batches. Each call returns the whole cnpjs array, and each CNPJ record is much larger than a CPF one.
• Set a maximum wait in the client (e.g. 30 min). Batch time depends on how many CNPJs are in the submission.
• On 5xx or a network error, try again on the next cycle. The GET is safe to repeat.

curl "https://api.cpfhub.io/cnpj/bulk/7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "x-api-key: $CPFHUB_API_KEY"

HTTP 200 OK

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "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-15T14:15:16.000Z",
    "updated_at": "2026-10-15T14:15:18.000Z",
    "cnpjs": [
      {
        "cnpj": "11222333000181",
        "found": true,
        "data": {
          "cnpj": "11222333000181",
          "razao_social": "EMPRESA EXEMPLO LTDA",
          "situacao_cadastral": "Ativa",
          "...": "other CNPJ Lookup fields"
        }
      },
      {
        "cnpj": "12ABC34501DE35",
        "found": false,
        "data": null
      }
    ]
  }
}

While "processing", the counters update at intervals and may lag behind cnpjs.

Errors

The API only responds in Portuguese. Error messages are shown as returned.

Error format and retries: Error Codes. Per-minute limit and credits: Usage Limits.

Details

Batch states

With overage, no CNPJ is skipped: all are looked up and the excess is charged.

Matching results to your list

cnpjs does not follow the submission order and does not include skipped or unprocessed items. Normalize your list (no dots, slash or hyphen, uppercase) and match on the cnpj field. The missing ones are the ones to resend (including invalid ones, which cost nothing).

const normalize = (cnpj: string) => cnpj.replace(/[./-]/g, '').toUpperCase()

const results = new Map(job.cnpjs.map((item) => [item.cnpj, item]))

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

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

More

• Submission is not idempotent: each accepted POST creates a new batch and charges the found items. If the connection drops without a jobId, check the dashboard or GET /quota before resending. With an error response, no batch was created.
• Credit: only found: true is charged, at the same cost and from the same allowance as the CPF Simple Lookup. Invalid, duplicate, not found and skipped items are not.
• Data source: the same as the CNPJ Lookup: the monthly public database of the Receita Federal, processed by OpenCNPJ. Data may be out of date until the next monthly update.
• Sample data: the CNPJs and the data above are fictional.

Updated on October 15, 2026