📦 Bulk API improvements

• New GET /bulks/{bulk_id}/items — a paginated endpoint to inspect individual items within a bulk, including a machine-readable status_code for every failure.
• Fixed consent-bulk observability — status endpoints now advance to a terminal state, so operators have a reliable stop condition for consent bulks.
• Improved RFC validation — mixed-case and lowercase RFCs are now normalized and accepted on POST /verifications.

⚙️ What Changes

1. New GET /bulks/{bulk_id}/items

List the items of any bulk with pagination and filters, so you can see exactly which entries failed and why instead of relying only on aggregate metrics.

• Query params: page (default 1), items_per_page (default 100, max 500), status (success | error), status_code, identifier.
• Each item returns identifier, verification_id (nullable), consent_id (nullable), status, status_code, and created_at. Items are ordered by created_at DESC.
• status_code is a closed catalog (e.g. rate_limit_exceeded, consent_not_found, invalid_identifier) documented in the Bulks section of the developer portal. Switch on status_code rather than the free-form internal detail.

{
  "items": [
    {
      "identifier": "FUVF580402HDFRLR05",
      "verification_id": null,
      "consent_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 }
}

2. Consent-bulk status now reports progress

• GET /consents/bulk/{bulk_id} now returns 200 with the same metrics shape as the verifications status endpoint (previously 404).
• GET /verifications/bulk/{bulk_id} now advances correctly for consent bulks — in_progress ticks down and the response reaches a terminal state (completed / failed) instead of staying frozen at total. Responses now also carry "type": "consent".

{ "bulk_id": "635ba6d5-…", "type": "consent", "metrics": { "total": 158, "completed": 158, "failed": 0, "in_progress": 0 } }

3. POST /verifications — RFCs are normalized before validation

• The rfc field is now normalized to uppercase before validation and persisted in normalized form, so structurally valid mixed-case or lowercase RFCs (e.g. Liaj930914l05) are accepted.
• When the value fails for a non-length reason, the error message now describes the actual problem instead of the misleading must be a valid RFC (12-13 characters) length message.

🛠️ No Action Required

These changes are additive or corrective and do not break existing integrations. Adopt the new GET /bulks/{bulk_id}/items endpoint and the consent-bulk status endpoints to gain item-level visibility and a reliable completion signal for your bulks.