Bulks

Overview

A bulk is a batch job that processes many identifiers at once. Instead of making one API call per identifier, you submit them all together, get a bulk_id back, and poll for status until the batch completes.

• Up to 100,000 items per bulk.
• Asynchronous: bulk creation returns 202 Accepted immediately. Items process in the background.
• Each item has its own status and status_code, so you can see exactly which identifiers succeeded, which failed, and why.

Use a bulk when you need to process more than ~50 identifiers at once and don't need synchronous results per identifier. For real-time results, use POST /verifications or POST /consents individually.

Bulk types

There are two kinds of bulks. Both are inspected through the same endpoints.

Both types are managed through:

• GET /bulks/{bulk_id}, status and metrics.
• GET /bulks/{bulk_id}/items, paginated list of items.
• DELETE /bulks/{bulk_id}, cancel and delete the bulk.

The response from GET /bulks/{bulk_id} includes a type field (consent or verification) so you always know which kind of bulk you're looking at.

Lifecycle

A bulk moves through this flow:

1. Create. Call POST /consents/bulk or POST /verifications/bulk with your list of identifiers. The API returns 202 Accepted with a bulk_id.
2. In progress. Items are processed asynchronously. The metrics object on GET /bulks/{bulk_id} tracks how many are done, failed, or still running.
3. Completed. When metrics.in_progress hits zero, the bulk is finished. completed + failed will equal total.
4. Inspect. If metrics.failed > 0, use GET /bulks/{bulk_id}/items?status=error to see each failed item with its status_code.

A metrics object looks like this:

{
  "total": 1000,
  "completed": 850,
  "failed": 50,
  "in_progress": 100
}

Recommended polling interval: every 30 seconds for bulks under 10k items, every 2 minutes for larger bulks. Don't poll more than once per 10 seconds.

while true; do
  response=$(curl -s -H "X-API-Key: $API_KEY" \
    https://api.burodeingresos.com/bulks/$BULK_ID)
  in_progress=$(echo $response | jq '.metrics.in_progress')
  if [ "$in_progress" = "0" ]; then
    echo "Done"
    break
  fi
  sleep 30
done

Inspecting items

When metrics.failed > 0, list the failed items to see which ones errored and why:

curl -H "X-API-Key: $API_KEY" \
  "https://api.burodeingresos.com/bulks/$BULK_ID/items?status=error&page=1&items_per_page=100"

Each item has:

Filters available on GET /bulks/{bulk_id}/items:

• status, success or error.
• status_code, any value from the catalog.
• identifier, exact match.

Pagination: default items_per_page is 100, max is 500. Walk pages until page > total_pages.

status_code catalog

Every item has a status_code. It's a closed enum with 13 values.

Code examples

Get bulk status

curl -H "X-API-Key: $API_KEY" \
  https://api.burodeingresos.com/bulks/4214c040-26c5-40c0-9526-afaff68eb97d

Response:

{
  "bulk_id": "4214c040-26c5-40c0-9526-afaff68eb97d",
  "external_id": null,
  "type": "verification",
  "created_at": "2026-05-20T17:37:14.133658Z",
  "metrics": {
    "total": 5,
    "completed": 0,
    "failed": 5,
    "in_progress": 0
  }
}

List failed items with a specific status code

curl -H "X-API-Key: $API_KEY" \
  "https://api.burodeingresos.com/bulks/$BULK_ID/items?status=error&status_code=rate_limit_exceeded"

Response:

{
  "items": [
    {
      "identifier": "FUVF580402HDFRLR05",
      "verification_id": null,
      "status": "error",
      "status_code": "rate_limit_exceeded",
      "created_at": "2026-05-20T17:37:14.133658Z"
    }
  ],
  "pagination": {
    "page": 1,
    "items_per_page": 100,
    "total_items": 5,
    "total_pages": 1
  }
}

Polling loop with failure inspection

#!/bin/bash
BULK_ID="4214c040-26c5-40c0-9526-afaff68eb97d"

while true; do
  response=$(curl -s -H "X-API-Key: $API_KEY" \
    "https://api.burodeingresos.com/bulks/$BULK_ID")

  in_progress=$(echo $response | jq '.metrics.in_progress')
  failed=$(echo $response | jq '.metrics.failed')

  if [ "$in_progress" = "0" ]; then
    break
  fi
  sleep 30
done

if [ "$failed" -gt "0" ]; then
  curl -H "X-API-Key: $API_KEY" \
    "https://api.burodeingresos.com/bulks/$BULK_ID/items?status=error"
fi

Migration from /verifications/bulk/{bulk_id}

If you're using the old endpoints, they still work as aliases but are now deprecated:

The new endpoints work for both consent and verification bulks. Migrate when you can, the old endpoints will be removed in a future release.