POST /iban/resolve/batch

Resolves a list of 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/resolve — structural validity (all ISO 13616 countries), issuing bank, BIC and reachability (countries covered by the local bank registry). The lookup is purely local → response in milliseconds.

One settlement for N IBANs amortises the per-call payment overhead for accounting and reconciliation agents that process lists. 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 are invalid (each is returned with valid: 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/resolve/batch
Content-Type: application/json

{
  "ibans": ["DE89370400440532013000", "FR1420041010050500013M02606"]
}

Each entry is trimmed before resolution. An empty string inside the array is not a request error: it is resolved as an invalid IBAN (valid: false), just like in the single call.

200 response — UnifiedResponse

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

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

See the single-call reference for the full field table (valid, country, bank_code, branch_code, bank, reachable, coverage, issue) and per-case examples. Each verdict also carries sepa_reachability — SEPA reachability per scheme (SCT, SCT Inst, SDD Core/B2B) — when the bank’s BIC is known, null otherwise.

Example — mixed batch (valid and invalid entries → 200)

{
  "data": {
    "count": 2,
    "results": [
      {
        "iban": "DE77100000000000000000",
        "valid": true,
        "country": "DE",
        "bank_code": "10000000",
        "branch_code": null,
        "bank": { "name": "Bundesbank", "bic": "MARKDEF1100" },
        "reachable": true,
        "coverage": "full",
        "issue": null
      },
      {
        "iban": "DE89370400440532013001",
        "valid": false,
        "country": null,
        "bank_code": null,
        "branch_code": null,
        "bank": null,
        "reachable": null,
        "coverage": null,
        "issue": "BAD_CHECKSUM"
      }
    ]
  },
  "provenance": {
    "source": "national-bank-registries",
    "fetched_at": "2026-06-12T09:30:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-11T00:00:00Z" }
  }
}

Errors

Only requests the service cannot answer leave the 200 range. The cap is checked before any resolution, 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/resolve — single-IBAN reference and full field documentation.
• For agents — discovery surfaces, the live /catalog and how settlement works.