POST /iban/repair/batch

Repairs a list of degraded IBANs in a single call: up to 500 IBANs, settled with one x402 payment for the whole batch. Each entry runs through the same engine as GET /iban/repair — check-digit recompute, recovery of unreadable characters marked with ?, candidates ranked known-bank first. The lookup is purely local → response in milliseconds.

One settlement for N IBANs amortises the per-call payment overhead for the reconciliation and invoice-ingestion agents that process lists of OCR’d IBANs. The batch is settled as one x402 payment for the whole call and priced per IBAN by the gateway (the first IBAN is roughly the price of the single call, then each additional IBAN adds to the total) — see the live /catalog for the authoritative price.

x402 golden rule: the agent pays for the answer to its question. A well-formed batch is a successful answer → 200, even when some of its IBANs cannot be repaired (each is returned with repaired: false, exactly as in the single call). The 4xx range is reserved for requests the service cannot answer (missing or malformed body, empty list, batch over the cap).

Request

POST with a JSON body. Set Content-Type: application/json.

POST /iban/repair/batch
Content-Type: application/json

{
  "ibans": ["DE89370400440532013?00", "DE89370400440532013001"]
}

Each entry is trimmed before repair and follows the same ? convention as the single call. An empty string inside the array is not a request error: it is returned with repaired: false, just like in the single call.

200 response — UnifiedResponse

{
  "data": {
    "count": 2,
    "results": [ { ... }, { ... } ]
  },
  "provenance": {
    "source": "national-bank-registries",
    "fetched_at": "2026-06-21T09:30:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-20T00:00:00Z" }
  }
}

• count: number of repaired IBANs, equal to results.length and to the number of IBANs submitted.
• results: one RepairResult per IBAN, in the same order as the input. Each element has exactly the same shape as the data of GET /iban/repair — including its own input field — so a caller can re-pair results without tracking indices.
• A single provenance block covers the whole batch: every IBAN is repaired against the same registry snapshot.

See the single-call reference for the full field table (input, repaired, already_valid, ambiguous, candidates, issue), the ? convention and per-case examples.

Example — mixed batch (repairable and unrepairable entries → 200)

{
  "data": {
    "count": 2,
    "results": [
      {
        "input": "DE8937040044053201300?",
        "repaired": true,
        "already_valid": false,
        "ambiguous": false,
        "candidates": [
          { "iban": "DE89370400440532013000", "bank_known": true, "resolution": { "...": "..." } }
        ],
        "issue": null
      },
      {
        "input": "DE????????440532013000",
        "repaired": false,
        "already_valid": false,
        "ambiguous": false,
        "candidates": [],
        "issue": "TOO_AMBIGUOUS"
      }
    ]
  },
  "provenance": {
    "source": "national-bank-registries",
    "fetched_at": "2026-06-21T09:30:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-20T00:00:00Z" }
  }
}

Errors

Only requests the service cannot answer leave the 200 range. The cap is checked before any repair, so an oversized batch is rejected without being billed an answer.

{ "error": "batch too large: 501 IBANs, the maximum is 500", "code": "BATCH_TOO_LARGE" }

See also

• GET /iban/repair — single-IBAN reference, the ? convention and full RepairResult field documentation.
• POST /iban/resolve/batch — resolve a list of IBANs to bank, BIC and reachability in one settlement.
• For agents — discovery surfaces, the live /catalog and how settlement works.