Batch CNPJ lookup

Sends up to 1,000 CNPJs at once. Processing is asynchronous: the API answers 202 with a batch_id and you follow the progress or wait for the webhook. The source is the same as the single lookup: the CNPJ open data.

Request body

[]arrayrequired

List of 1 to 1,000 items.

[].cnpjstringrequired

CNPJ with or without punctuation, numeric or alphanumeric. You can also send the list as plain CNPJ strings.

1 credit per item found.

• Your balance must cover the whole batch, unless your plan allows overage. Without enough balance the answer is 402 and the batch does not start.
• Invalid items (format or check digit), items not found and source failures are not charged. You can resend only the ones that failed.
• The batch uses the same balance and the same request limits as the single lookup.

How a batch is processed

1. 1

   You send the list

   The API validates the format and check digits of each item and queues the work. The 202 response carries the batch_id.

2. 2

   Processing runs in the background

   Each CNPJ is resolved from the open data, and only the ones found are charged.

3. 3

   You follow progress

   Poll GET /v1/cnpj/batch/{id} until the status is completed, or receive the batch.completed event on your webhook.

4. 4

   You read the results

   Results come paginated and stay available for 24 hours.

202 response fields

batch_idstring

Batch identifier. Use it to follow progress.

statusstring

processing or completed.

totalnumber

Number of items in the batch.

processednumber

Items already resolved (at first, only the invalid ones).

found / not_found / invalid / errorsnumber

Counters by result so far.

status_urlstring

Path to follow the batch. Also sent in the Location header.

credits_remainingnumber

Current balance. It can be hidden in the dashboard.