Bulk IBAN Validation API: Verify Thousands of IBANs in Seconds

When you are processing a single payment, validating one IBAN at a time works fine. But when you are running payroll for 5,000 employees, onboarding a batch of 2,000 new vendors, or migrating account data from a legacy system, making thousands of individual API calls is slow, expensive, and unnecessarily complex.

Edge's Bulk IBAN Validation API solves this by accepting an array of IBANs in a single request and returning granular validation results for each one. You get the same comprehensive checks — format, length, checksum, country rules, and bank code resolution — applied to every IBAN in the batch, with individual error reporting so you know exactly which accounts need attention.

Why Bulk Validation Matters

The Scale Problem

Financial operations at scale involve large volumes of bank account data. Consider these common scenarios:

• Monthly payroll. A mid-size company with 3,000 employees needs to validate all bank accounts before each payroll run. Employees change banks, make typos when updating details, and accounts get closed.
• Vendor onboarding. A procurement platform imports a supplier file with 1,500 new vendor bank accounts. Each one needs validation before the first payment can be scheduled.
• System migration. A bank migrating from a legacy core system to a modern platform needs to validate 500,000 customer IBANs to identify corrupt or outdated records.
• Payment file pre-processing. A payment service provider receives batch files containing thousands of credit transfers. Validating every IBAN before submission to the clearing network prevents costly rejects.

In all of these cases, you need validation that is fast, cost-effective, and provides per-record error detail.

The Cost of Individual Calls

If you validate IBANs one at a time using the full validation endpoint, you pay 3 credits per IBAN and incur the HTTP overhead of thousands of separate requests. For a payroll file with 5,000 employees, that means 5,000 HTTP round trips and 15,000 credits.

The Bulk IBAN Validation API charges 2 credits per IBAN — a 33% cost reduction compared to individual full validation. And because you send one request instead of thousands, your total processing time drops from minutes to seconds.

Approach	5,000 IBANs	Credits Used	HTTP Requests
Individual full validation	~5 minutes	15,000	5,000
Bulk validation API	~3 seconds	10,000	1

How the API Works

Request Format

Send a POST request with an array of IBANs. Each entry in the array is an object with the IBAN string and an optional reference ID that you can use to correlate results with your internal records.

curl -X POST https://api.edge.bh/v1/services/iban/validate-bulk \
  -H "X-Api-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "ibans": [
      {"iban": "DE89370400440532013000", "reference": "EMP-001"},
      {"iban": "GB29NWBK60161331926819", "reference": "EMP-002"},
      {"iban": "FR7630006000011234567890189", "reference": "EMP-003"},
      {"iban": "INVALID123", "reference": "EMP-004"},
      {"iban": "BH67BMAG00001299123456", "reference": "EMP-005"}
    ]
  }'

Response Format

The response contains a results array with one entry per submitted IBAN, preserving the input order. Each result includes the same detailed validation data you would get from the individual endpoint — valid/invalid status, parsed IBAN components, country data, bank details, and granular validation flags.

{
  "total": 5,
  "valid_count": 4,
  "invalid_count": 1,
  "results": [
    {
      "reference": "EMP-001",
      "valid": true,
      "iban": {
        "formatted": "DE89 3704 0044 0532 0130 00",
        "electronic": "DE89370400440532013000",
        "country_code": "DE",
        "check_digits": "89",
        "bban": "370400440532013000"
      },
      "country": {
        "name": "Germany",
        "iso": "DE",
        "sepa": true,
        "iban_length": 22
      },
      "bank": {
        "name": "Commerzbank",
        "bic": "COBADEFFXXX",
        "bank_code": "37040044"
      },
      "validations": {
        "format": true,
        "length": true,
        "checksum": true,
        "country_code": true,
        "bban_structure": true,
        "bank_code": true
      }
    },
    {
      "reference": "EMP-004",
      "valid": false,
      "iban": {
        "electronic": "INVALID123"
      },
      "validations": {
        "format": false,
        "length": false,
        "checksum": false,
        "country_code": false,
        "bban_structure": false,
        "bank_code": false
      },
      "errors": [
        "Invalid IBAN format: must start with 2 letters followed by 2 digits",
        "Unrecognized country code"
      ]
    }
  ]
}

Notice that invalid IBANs include an errors array with human-readable descriptions of what failed. This makes it straightforward to generate error reports for operations teams without writing custom error-mapping logic.

Batch Size Limits

The API accepts up to 1,000 IBANs per request. For larger datasets, you will need to split your data into chunks and make multiple requests. Here is a practical implementation:

const BATCH_SIZE = 1000;

async function validateAllIbans(ibanRecords, apiKey) {
  const results = [];

  // Split into chunks of 1,000
  for (let i = 0; i < ibanRecords.length; i += BATCH_SIZE) {
    const batch = ibanRecords.slice(i, i + BATCH_SIZE);

    const response = await fetch(
      'https://api.edge.bh/v1/services/iban/validate-bulk',
      {
        method: 'POST',
        headers: {
          'X-Api-Key': apiKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          ibans: batch.map((record) => ({
            iban: record.iban,
            reference: record.id,
          })),
        }),
      }
    );

    const data = await response.json();
    results.push(...data.results);
  }

  return results;
}

// Usage
const employees = [
  { id: 'EMP-001', iban: 'DE89370400440532013000', name: 'Hans Mueller' },
  { id: 'EMP-002', iban: 'GB29NWBK60161331926819', name: 'Jane Smith' },
  // ... thousands more
];

const validationResults = await validateAllIbans(employees, process.env.EDGE_API_KEY);

const invalid = validationResults.filter((r) => !r.valid);
console.log(`${invalid.length} IBANs failed validation`);
invalid.forEach((r) => {
  console.log(`  ${r.reference}: ${r.errors.join(', ')}`);
});

Per-IBAN Error Handling

One of the most important aspects of bulk validation is granular error reporting. When 50 out of 5,000 IBANs fail, you need to know exactly which ones failed and why, so you can route them to the right resolution process.

The validations object on each result tells you precisely which check failed:

Validation	Failed Meaning
format	IBAN contains invalid characters or does not start with 2 letters + 2 digits
length	IBAN length does not match the expected length for the country
checksum	MOD-97 check digit verification failed — likely a typo
country_code	The 2-letter prefix is not a recognized IBAN country
bban_structure	The BBAN portion does not match the country's expected structure
bank_code	The bank code was not found in the financial institution directory

This granularity lets you build smart error handling. A checksum failure is almost certainly a typo — prompt the user to re-enter the IBAN. A bank code failure might mean the bank has been acquired and the code reassigned — flag it for manual review. A format failure on an imported record might indicate a data encoding issue in the source system.

Use Cases in Detail

Payroll Pre-Validation

Payroll is the highest-stakes batch payment process for most organizations. A failed salary transfer is not just a financial problem — it is a legal and employee-relations problem. In many jurisdictions, employers face penalties for late salary payments.

Build bulk IBAN validation into your payroll pipeline as a pre-flight check:

async function preValidatePayroll(payrollRun) {
  const results = await validateAllIbans(
    payrollRun.employees.map((emp) => ({
      id: emp.employeeId,
      iban: emp.bankAccount.iban,
    })),
    process.env.EDGE_API_KEY
  );

  const failures = results.filter((r) => !r.valid);

  if (failures.length > 0) {
    // Block payroll execution and notify HR
    await notifyHR({
      subject: `Payroll ${payrollRun.id}: ${failures.length} invalid IBANs detected`,
      failures: failures.map((f) => ({
        employeeId: f.reference,
        errors: f.errors,
      })),
    });
    return { approved: false, failures };
  }

  return { approved: true };
}

Run this 24-48 hours before the payroll execution date. This gives HR time to contact employees with invalid bank details and collect corrected information.

Vendor and Supplier Onboarding

When your accounts payable team imports a batch of new suppliers from a spreadsheet or ERP export, validate all bank details before they enter your payment system. This prevents the first payment to a new vendor from bouncing — which is a terrible first impression.

Data Migration and Cleanup

Legacy systems often contain bank account data in inconsistent formats — domestic account numbers mixed with IBANs, leading zeros stripped, spaces and hyphens in random positions. During migration, bulk validation helps you:

1. Identify which records are already valid IBANs.
2. Flag records that fail validation for manual review or conversion.
3. Verify that converted domestic-to-IBAN records are correct.

# Validate a CSV of IBANs using jq to format the request
cat accounts.csv | jq -R -s '
  split("\n") | map(select(length > 0)) |
  to_entries | map({iban: .value, reference: ("ROW-" + (.key | tostring))}) |
  {ibans: .}
' | curl -X POST https://api.edge.bh/v1/services/iban/validate-bulk \
    -H "X-Api-Key: $EDGE_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- > validation_results.json

Payment File Pre-Screening

Payment service providers and banks that process SEPA batch files (pain.001 XML) can validate all IBANs before submitting to the clearing system. Catching invalid IBANs before submission prevents reject fees, reduces operational overhead, and improves straight-through processing rates.

If you are also screening beneficiaries, consider pairing bulk IBAN validation with our Sanctions Screening API to cover both data quality and compliance in a single pre-processing step.

Performance and Throughput

The Bulk IBAN Validation endpoint is optimized for throughput. A batch of 1,000 IBANs typically processes in 2-4 seconds, depending on the mix of countries (some countries require more complex BBAN structure checks than others).

For very large datasets (100,000+ IBANs), we recommend:

• Parallel requests. Split your data into 1,000-IBAN chunks and send multiple requests concurrently. Edge's API supports concurrent requests per API key.
• Async processing. For non-time-critical jobs like nightly data cleanup, process batches sequentially with a small delay between requests to stay comfortably within rate limits.
• Streaming results. Process each batch response as it arrives rather than waiting for all batches to complete. This reduces memory usage for very large datasets.

// Parallel batch processing with concurrency limit
async function validateLargeDataset(records, apiKey, concurrency = 5) {
  const batches = [];
  for (let i = 0; i < records.length; i += BATCH_SIZE) {
    batches.push(records.slice(i, i + BATCH_SIZE));
  }

  const allResults = [];
  for (let i = 0; i < batches.length; i += concurrency) {
    const chunk = batches.slice(i, i + concurrency);
    const batchResults = await Promise.all(
      chunk.map((batch) =>
        fetch('https://api.edge.bh/v1/services/iban/validate-bulk', {
          method: 'POST',
          headers: {
            'X-Api-Key': apiKey,
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            ibans: batch.map((r) => ({ iban: r.iban, reference: r.id })),
          }),
        }).then((res) => res.json())
      )
    );
    batchResults.forEach((r) => allResults.push(...r.results));
  }

  return allResults;
}

Credit Efficiency

Bulk validation is priced at 2 credits per IBAN, compared to 3 credits for individual full validation. This 33% savings adds up quickly at scale:

Volume	Individual Cost	Bulk Cost	Savings
1,000 IBANs	3,000 credits	2,000 credits	1,000 credits
10,000 IBANs	30,000 credits	20,000 credits	10,000 credits
100,000 IBANs	300,000 credits	200,000 credits	100,000 credits

If your use case only requires format and checksum validation (no bank data lookup), consider the Basic IBAN Validation endpoint at 1 credit per IBAN. Basic validation is sufficient for form-level pre-screening where you just need to catch typos, but for payment execution, full validation through the bulk endpoint is the better choice.

Sign up on the Edge dashboard to get your API key and start validating at scale.

Building a Validation Pipeline

For organizations that process payments regularly, we recommend building a validation pipeline that runs automatically:

1. Ingest. New bank account data enters your system via forms, file uploads, or API integrations.
2. Queue. Collect new and recently updated IBANs into a validation queue.
3. Batch. At regular intervals (or when the queue reaches a threshold), pull records from the queue and validate them via the Bulk API.
4. Triage. Route valid IBANs to the payment-ready pool. Route invalid IBANs to the exception queue with specific error details.
5. Resolve. Operations or support teams work the exception queue — contacting account holders for corrections.
6. Re-validate. Corrected IBANs go back through the pipeline.

This approach ensures that by the time a payment is executed, every IBAN has been validated and any issues have been resolved. The cost of a few credits per validation is negligible compared to the cost of a single failed payment.

For a deeper understanding of what each validation check does, refer to our complete IBAN validation guide.

Frequently Asked Questions

What is the maximum number of IBANs per bulk request?

The Bulk IBAN Validation API accepts up to 1,000 IBANs per request. For larger datasets, split your data into chunks of 1,000 and send multiple requests. You can send these requests concurrently to maximize throughput — see the parallel processing code example above.

How is bulk validation different from calling the individual endpoint in a loop?

Three key differences: cost (2 credits per IBAN vs. 3), speed (one HTTP request vs. thousands), and error handling (consolidated response with per-IBAN detail vs. managing thousands of individual responses). The validation checks performed on each IBAN are identical — format, length, checksum, country rules, BBAN structure, and bank code resolution.

Does the bulk endpoint return bank details (BIC, bank name) like the individual endpoint?

Yes. Each result in the bulk response includes the same bank data that the individual full validation endpoint returns — bank name, BIC/SWIFT code, bank code, and branch information (where available). The only difference is pricing: 2 credits per IBAN in bulk vs. 3 credits individually.

How should I handle partial failures in a bulk request?

The API always returns results for every submitted IBAN, even if some are invalid. It never short-circuits on the first error. Check the valid field on each result individually. The top-level valid_count and invalid_count fields give you a quick summary, and you can filter the results array to extract only the failures for your exception handling workflow.

Can I use the reference field to match results back to my records?

Yes, that is exactly what the reference field is for. Whatever string you pass as reference for each IBAN is echoed back in the corresponding result. Use your internal record ID (employee ID, vendor ID, account ID) so you can map validation results directly to your database records without relying on array order.

What happens if I submit duplicate IBANs in the same batch?

Each IBAN in the array is validated independently, even if duplicates exist. You will receive a separate result for each entry. If you want to avoid paying for duplicate validations, deduplicate your input array before sending the request and map the result back to all original records that share that IBAN.