Batch Validate

Validate up to 100 IBANs in a single API call. Each IBAN is processed independently — one invalid IBAN does not affect the others. Paid per call in USDC via x402, an IBAN costs $0.002 in a batch instead of $0.005 on its own; on an API key or a credit pack, each IBAN uses one request or credit, the same as a single validation.

Endpoint

POST https://api.ibanforge.com/v1/iban/batch

Cost: $0.002 USDC per IBAN via x402 (e.g. 10 IBANs = $0.020, 100 IBANs = $0.200). On an API key, a batch debits 1 request / 1 prepaid credit per IBAN — free tier and credit packs alike. If the batch exceeds your remaining allowance, the API refuses it all-or-nothing with a 402 naming the shortfall (X-Credits-Required / X-Quota-Required headers); nothing is consumed.

Request

Headers

Header	Value	Required
`Content-Type`	`application/json`	Yes
`Authorization`	`Bearer ifk_...` (free API key)	One of the two
`X-PAYMENT`	x402 payment token	One of the two

Body

{
  "ibans": [
    "CH10 0023 0000 0000 1234 5",
    "DE89 3704 0044 0532 0130 00",
    "INVALID123"
  ]
}

Field	Type	Description
`ibans`	`string[]`	Array of IBANs to validate. 1 to 100 items.

Response

Success (200)

{
  "results": [
    {
      "iban": "CH1000230000000012345",
      "valid": true,
      "country": { "code": "CH", "name": "Switzerland" },
      "check_digits": "10",
      "bban": { "bank_code": "00230", "account_number": "000000012345" },
      "bic": { "code": "UBSWCHZH80A", "bic8": "UBSWCHZH", "bank_name": "UBS Switzerland AG", "city": "Zürich" },
      "sepa": { "member": true, "schemes": ["SCT", "SDD"], "vop_required": false },
      "issuer": { "type": "bank", "name": "UBS Switzerland AG" },
      "risk_indicators": {
        "issuer_type": "bank",
        "country_risk": "standard",
        "test_bic": false,
        "sepa_reachable": true,
        "vop_coverage": false
      },
      "clearing": {
        "iid": "00230",
        "name": "UBS Switzerland AG",
        "type": "bank",
        "town": "Zürich",
        "sic": true,
        "instant_payments_chf": true,
        "eurosic": true,
        "qr_iid": null
      },
      "formatted": "CH10 0023 0000 0000 1234 5",
      "cost_usdc": 0.002
    },
    {
      "iban": "DE89370400440532013000",
      "valid": true,
      "country": { "code": "DE", "name": "Germany" },
      "check_digits": "89",
      "bban": { "bank_code": "37040044", "account_number": "0532013000" },
      "bic": { "code": "COBADEFFXXX", "bank_name": "Commerzbank", "city": "Köln" },
      "sepa": { "member": true, "schemes": ["SCT", "SDD", "SCT_INST"], "vop_required": true },
      "issuer": { "type": "bank", "name": "Commerzbank" },
      "risk_indicators": {
        "issuer_type": "bank",
        "country_risk": "standard",
        "test_bic": false,
        "sepa_reachable": true,
        "vop_coverage": true
      },
      "formatted": "DE89 3704 0044 0532 0130 00",
      "cost_usdc": 0.002
    },
    {
      "iban": "INVALID123",
      "valid": false,
      "error": "unsupported_country",
      "error_detail": "Country code 'IN' is not a recognized IBAN country.",
      "cost_usdc": 0.002
    }
  ],
  "count": 3,
  "valid_count": 2,
  "cost_usdc": 0.006,
  "processing_ms": 1.05
}

Response fields

Top-level:

Field	Type	Description
`results`	`array`	Array of validation results, same order as input
`count`	`number`	Total IBANs processed
`valid_count`	`number`	Count of valid IBANs
`cost_usdc`	`number`	Total cost for this batch
`processing_ms`	`number`	Total processing time

Each item in results has the same structure as the single validation response, including sepa, issuer, and risk_indicators for valid IBANs.

Errors

Status	Code	Description
400	`empty_batch`	The `ibans` array is empty
400	`batch_too_large`	More than 100 IBANs submitted
400	`invalid_request`	Request body is not valid JSON or missing `ibans` field

Code examples

cURL

curl -X POST https://api.ibanforge.com/v1/iban/batch \
  -H "Content-Type: application/json" \
  -d '{
    "ibans": [
      "CH1000230000000012345",
      "DE89370400440532013000",
      "FR7630006000011234567890189"
    ]
  }'

Python

import requests
 
response = requests.post(
    "https://api.ibanforge.com/v1/iban/batch",
    json={
        "ibans": [
            "CH1000230000000012345",
            "DE89370400440532013000",
            "FR7630006000011234567890189",
        ]
    },
)
 
data = response.json()
print(f"Valid: {data['valid_count']}/{data['count']}")
 
for result in data["results"]:
    if result["valid"]:
        risk = result["risk_indicators"]["country_risk"]
        issuer = result["issuer"]["type"]
        print(f"  {result['iban']} — {result['country']['name']} ({issuer}, risk: {risk})")
    else:
        print(f"  INVALID — {result['error_detail']}")

TypeScript

const response = await fetch(
  "https://api.ibanforge.com/v1/iban/batch",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      ibans: [
        "CH1000230000000012345",
        "DE89370400440532013000",
        "FR7630006000011234567890189",
      ],
    }),
  }
);
 
const data = await response.json();
console.log(`Valid: ${data.valid_count}/${data.count}`);
 
for (const result of data.results) {
  if (result.valid) {
    console.log(`  ${result.iban} — ${result.issuer.type}, risk: ${result.risk_indicators.country_risk}`);
  } else {
    console.log(`  INVALID — ${result.error_detail}`);
  }
}

Put these checks to work

Choose a first step for your software or your supplier file.

Check a supplier file

Upload a CSV or Excel file and preview the findings for free. Purchase the annotated workbook if you need the full report. No account or subscription required.

Explore the file audit

Integrate IBAN checks into your software

Try a validation, inspect the response, then connect your application through the API or an existing integration.

Explore the API workflow

Available bank information varies by country and source. These checks do not confirm the account holder or guarantee that a payment will succeed.