Batch CPF lookup

Sends up to 1,000 CPFs at once. Processing is asynchronous: the API answers 202 with a batch_id and you follow the progress or wait for the webhook.

Request body

[]arrayrequired

List of 1 to 1,000 items. Repeated CPFs count once.

[].cpfstringrequired

CPF, with or without punctuation.

[].birthdatestringrequired

Date of birth, YYYY-MM-DD.

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, not found items and provider failures are not charged. You can resend only the ones that failed.

How a batch is processed

1. 1

   You send the list

   The API validates each item and queues the work. The 202 response carries the batch_id.

2. 2

   Fast answers

   Whatever was looked up recently is resolved right away. The rest goes to the official source in the background.

3. 3

   You follow progress

   Poll GET /v1/cpf/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.

found / not_found / invalid / errorsnumber

Counters per outcome so far.

status_urlstring

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

credits_remainingnumber

Balance after the items already charged. Can be hidden in the dashboard.