POST /iban/screen/batch

Screens 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/screen — sanctioned bank/BIC (OFAC / EU / UN) and jurisdiction risk (FATF black/grey, embargoes, EU-AML), aggregated into a single risk band. The lookup is purely local → response in milliseconds.

One settlement for N IBANs fits the KYB / onboarding persona, which screens lists of counterparties by nature. 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 returned with valid: false, screening: null) or risky (each returned with its own band). The 4xx range is reserved for requests the service cannot answer (missing or malformed body, empty list, batch over the cap).

Scope and limits

Same as the single call: bank/BIC sanctions and jurisdiction risk only, no account-holder name screening (Verification of Payee is a distinct product), and not a legal compliance opinion. See GET /iban/screen.

Request

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

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

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

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

200 response — UnifiedResponse

{
  "data": {
    "count": 2,
    "results": [ { ... }, { ... } ]
  },
  "provenance": {
    "source": "ofac-eu-un-sanctions",
    "fetched_at": "2026-06-20T09:30:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-19T00:00:00Z" }
  }
}

• count: number of screened 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/screen — 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 screened against the same lists snapshot.

See the single-call reference for the full field tables (screening, jurisdiction, hits, risk band semantics) and per-case examples.

Example — mixed batch (clean and prohibited entries → 200)

{
  "data": {
    "count": 2,
    "results": [
      {
        "iban": "DE77100000000000000000",
        "valid": true,
        "country": "DE",
        "bank_code": "10000000",
        "bank": { "name": "Bundesbank", "bic": "MARKDEF1100" },
        "screening": {
          "risk": "clear",
          "bank_sanctioned": false,
          "jurisdiction": { "level": "clear", "lists": [] },
          "hits": []
        },
        "coverage": "full",
        "issue": null
      },
      {
        "iban": "DE89370400440532013001",
        "valid": false,
        "country": null,
        "bank_code": null,
        "bank": null,
        "screening": null,
        "coverage": "structure_only",
        "issue": "BAD_CHECKSUM"
      }
    ]
  },
  "provenance": {
    "source": "ofac-eu-un-sanctions",
    "fetched_at": "2026-06-20T09:30:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-19T00:00:00Z" }
  }
}

Errors

Only requests the service cannot answer leave the 200 range. The cap is checked before any screening, 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/screen — single-IBAN reference, full field documentation and risk band semantics.
• POST /iban/resolve/batch — resolve a batch of IBANs to their bank, BIC and reachability.
• For agents — discovery surfaces, the live /catalog and how settlement works.