IBAN Validation API

Part of the IBAN Suite service. One request validates an IBAN in six independent checks, identifies the issuing bank and branch with its BIC and address, and reports the bank’s SEPA scheme reachability. Every check comes back as its own coded result, so your code can act on the one it needs instead of parsing messages.

Endpoint

• HTTPS only. POST bodies are application/x-www-form-urlencoded; GET takes the same parameters in the query string. Both methods return the same response.
• The HTTP status is 200 for every processed request, whether the IBAN is valid or not and also for account errors; the outcome is in the response body. The only other statuses are 429 when the rate limit is exceeded (a short HTML page, not JSON or XML, so check the status before parsing) and 500 with an empty body for a parameter sent in a form the API cannot read, such as iban[].
• A 200 with an empty body means the request was not understood: iban, api_key or format is missing, or format is not exactly json or xml (JSON in upper case is not accepted). Check for an empty body before parsing.
• Responses are UTF-8. The Content-Type follows the format parameter.
• Submitted IBANs and the responses to them are not stored on our servers.

Your first request

1. Copy your key from API Access.
2. Run, with the key in place of YOUR_API_KEY:

curl "https://api.iban.com/clients/api/v4/iban/" -d api_key=YOUR_API_KEY -d format=json -d iban=FR7630006000011234567890189

The full response to this request is in the Response section; the same request in six more languages is under Example request.

Keeping the key safe

• Use POST in production. With GET the key is part of the URL and ends up in proxy, load-balancer and web-server access logs; with POST it travels in the request body.
• Call the API from your server. A key embedded in browser JavaScript or a mobile app can be read from the source or the network traffic.
• Restrict the key to the IP addresses of your servers under Settings; requests from anywhere else get 305.
• Keep the key out of source control; load it from an environment variable or a configuration file. A key cannot be regenerated from the client area: if it is exposed, contact support to have it replaced.

Request parameters

Example request

Every example validates the same IBAN, FR7630006000011234567890189, the registry example for France; its response is shown under Response. Replace YOUR_API_KEY with the key from API Access.

curl "https://api.iban.com/clients/api/v4/iban/" \
  -d api_key=YOUR_API_KEY \
  -d format=json \
  -d iban=FR7630006000011234567890189

<?php
$ch = curl_init('https://api.iban.com/clients/api/v4/iban/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'api_key' => 'YOUR_API_KEY',
        'format'  => 'json',
        'iban'    => 'FR7630006000011234567890189',
    ]),
]);
$result = json_decode(curl_exec($ch), true);   // the whole response as an array
curl_close($ch);

echo json_encode($result, JSON_PRETTY_PRINT), PHP_EOL;

import json
import requests

r = requests.post('https://api.iban.com/clients/api/v4/iban/', data={
    'api_key': 'YOUR_API_KEY',
    'format': 'json',
    'iban': 'FR7630006000011234567890189',
})
result = r.json()   # the whole response as a dict
print(json.dumps(result, indent=3))

const body = new URLSearchParams({
  api_key: 'YOUR_API_KEY',
  format: 'json',
  iban: 'FR7630006000011234567890189',
});

fetch('https://api.iban.com/clients/api/v4/iban/', { method: 'POST', body })
  .then(res => res.json())
  .then(result => console.log(JSON.stringify(result, null, 3)));   // result: the whole response as an object

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class IbanApi {
    public static void main(String[] args) throws Exception {
        String body = "api_key=YOUR_API_KEY&format=json&iban=FR7630006000011234567890189";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.iban.com/clients/api/v4/iban/"))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());   // the whole JSON response; parse it with Jackson or Gson
    }
}

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Text.Json;
using System.Text.Json.Nodes;

var client = new HttpClient();
var form = new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["api_key"] = "YOUR_API_KEY",
    ["format"]  = "json",
    ["iban"]    = "FR7630006000011234567890189",
});
var response = await client.PostAsync("https://api.iban.com/clients/api/v4/iban/", form);
var result = JsonNode.Parse(await response.Content.ReadAsStringAsync());   // the whole response
Console.WriteLine(result?.ToJsonString(new JsonSerializerOptions { WriteIndented = true }));

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
)

func main() {
	form := url.Values{
		"api_key": {"YOUR_API_KEY"},
		"format":  {"json"},
		"iban":    {"FR7630006000011234567890189"},
	}
	resp, err := http.PostForm("https://api.iban.com/clients/api/v4/iban/", form)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]any // the whole response
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		panic(err)
	}
	out, _ := json.MarshalIndent(result, "", "   ")
	fmt.Println(string(out))
}

With the optional parameters

The same request asking for SEPA Instant reachability and transliteration:

curl "https://api.iban.com/clients/api/v4/iban/" \
  -d api_key=YOUR_API_KEY \
  -d format=json \
  -d iban=FR7630006000011234567890189 \
  -d sci=1 -d sci_tips=1 -d translit=1

The response is the same as above except that sepa_data gains two members after SCT, and bank, address and city are returned in plain Latin letters (nothing changes for this French bank; an Austrian one would come back as Vockla instead of Vöckla):

"sepa_data": {
   "SCT": "YES",
   "SCI": "YES",
   "SCI_TIPS": "YES",
   "SDD": "YES",
   "COR1": "YES",
   "B2B": "YES",
   "SCC": "NO"
}

Send only the options you need: each one is 1 to switch it on; any other value or leaving it out switches it off.

Test data and countries

• Test IBAN numbers with the expected outcome of every check: a valid IBAN per country plus up to five variants that each break one thing, each with the six codes the API returns.
• IBAN structure & examples for all countries, plus experimental partial-IBAN countries: country code, SEPA membership, length, account check, branch code and a sample IBAN.
• All 89 countries of the ISO 13616 IBAN registry are validated. The registry page also lists the territories that use another country’s IBAN code: French overseas departments and collectivities under FR, Isle of Man, Guernsey and Jersey under GB, Åland under FI, Azores and Madeira under PT, Canary Islands, Ceuta and Melilla under ES. A country code that is neither in the registry nor on the partial list is answered with 207.
• Test requests go to the same endpoint and use queries like any other request; there is no separate sandbox for this API.

Response

Four objects, always present and always in this order: bank_data, sepa_data, validations, errors. The response to the example request:

{
   "bank_data": {
      "bic": "AGRIFRPPXXX",
      "branch": "AG SIEGE",
      "bank": "CREDIT AGRICOLE S A",
      "address": "12 PL DES ETATS UNIS",
      "city": "MONTROUGE CEDEX",
      "state": null,
      "zip": "92127",
      "phone": null,
      "fax": null,
      "www": null,
      "email": null,
      "country": "France",
      "country_iso": "FR",
      "account": "1234567890189",
      "bank_code": "30006",
      "branch_code": "00001"
   },
   "sepa_data": {
      "SCT": "YES",
      "SDD": "YES",
      "COR1": "YES",
      "B2B": "YES",
      "SCC": "NO"
   },
   "validations": {
      "chars": {
         "code": "006",
         "message": "IBAN does not contain illegal characters"
      },
      "account": {
         "code": "002",
         "message": "Account Number check digit is correct"
      },
      "iban": {
         "code": "001",
         "message": "IBAN Check digit is correct"
      },
      "structure": {
         "code": "005",
         "message": "IBAN structure is correct"
      },
      "length": {
         "code": "003",
         "message": "IBAN Length is correct"
      },
      "country_support": {
         "code": "007",
         "message": "Country supports IBAN standard"
      }
   },
   "errors": []
}

<?xml version="1.0"?>
<result>
   <bank_data>
      <bic>AGRIFRPPXXX</bic>
      <branch>AG SIEGE</branch>
      <bank>CREDIT AGRICOLE S A</bank>
      <address>12 PL DES ETATS UNIS</address>
      <city>MONTROUGE CEDEX</city>
      <state/>
      <zip>92127</zip>
      <phone/>
      <fax/>
      <www/>
      <email/>
      <country>France</country>
      <country_iso>FR</country_iso>
      <account>1234567890189</account>
      <bank_code>30006</bank_code>
      <branch_code>00001</branch_code>
   </bank_data>
   <sepa_data>
      <SCT>YES</SCT>
      <SDD>YES</SDD>
      <COR1>YES</COR1>
      <B2B>YES</B2B>
      <SCC>NO</SCC>
   </sepa_data>
   <validations>
      <chars>
         <code>006</code>
         <message>IBAN does not contain illegal characters</message>
      </chars>
      <iban>
         <code>001</code>
         <message>IBAN Check digit is correct</message>
      </iban>
      <account>
         <code>002</code>
         <message>Account Number check digit is correct</message>
      </account>
      <structure>
         <code>005</code>
         <message>IBAN structure is correct</message>
      </structure>
      <length>
         <code>003</code>
         <message>IBAN Length is correct</message>
      </length>
      <country_support>
         <code>007</code>
         <message>Country supports IBAN standard</message>
      </country_support>
   </validations>
   <errors/>
</result>

bank_data

The four fields marked always are read from the IBAN itself and are filled whenever the country is known and the IBAN parses, even when a check fails; branch_code is read the same way but is empty for the countries whose IBAN has no branch part. The other eleven come from the bank directory and are filled only when a bank is identified. Bank identification is attempted only when the check digits (iban 001) and the length (length 003) are correct. A field without a value is null in JSON and an empty element in XML; responses in which the bank lookup was skipped currently return an empty string instead of null, so treat both alike.

sepa_data

Scheme reachability of the identified bank, YES or NO. All NO when no bank is identified. The schemes are explained in the glossary.

validations

Six members, one per check: chars, iban, length, structure, account, country_support. Each holds a code and a message. Codes are three-character strings with a leading zero ("006", not 6); compare them as strings. The order of the members differs between JSON and XML, so address them by name. All six are present whenever the request was accepted.

errors

Empty when the request was accepted. On an account error it holds one entry with code and message, and the other three objects are empty.

Response to a failed validation

The same IBAN with the check digits changed from 76 to 77. The bank identifier is read from the IBAN, but no lookup is made and the SEPA flags are NO:

{
   "bank_data": {
      "bic": null,
      "branch": null,
      "bank": null,
      "address": null,
      "city": null,
      "state": null,
      "zip": null,
      "phone": null,
      "fax": null,
      "www": null,
      "email": null,
      "country": "France",
      "country_iso": "FR",
      "account": "1234567890189",
      "bank_code": "30006",
      "branch_code": "00001"
   },
   "sepa_data": {
      "SCT": "NO",
      "SDD": "NO",
      "COR1": "NO",
      "B2B": "NO",
      "SCC": "NO"
   },
   "validations": {
      "chars": {
         "code": "006",
         "message": "IBAN does not contain illegal characters"
      },
      "account": {
         "code": "002",
         "message": "Account Number check digit is correct"
      },
      "iban": {
         "code": "202",
         "message": "IBAN Check digit not correct"
      },
      "structure": {
         "code": "005",
         "message": "IBAN structure is correct"
      },
      "length": {
         "code": "003",
         "message": "IBAN Length is correct"
      },
      "country_support": {
         "code": "007",
         "message": "Country supports IBAN standard"
      }
   },
   "errors": []
}

<?xml version="1.0"?>
<result>
   <bank_data>
      <bic/>
      <branch/>
      <bank/>
      <address/>
      <city/>
      <state/>
      <zip/>
      <phone/>
      <fax/>
      <www/>
      <email/>
      <country>France</country>
      <country_iso>FR</country_iso>
      <account>1234567890189</account>
      <bank_code>30006</bank_code>
      <branch_code>00001</branch_code>
   </bank_data>
   <sepa_data>
      <SCT>NO</SCT>
      <SDD>NO</SDD>
      <COR1>NO</COR1>
      <B2B>NO</B2B>
      <SCC>NO</SCC>
   </sepa_data>
   <validations>
      <chars>
         <code>006</code>
         <message>IBAN does not contain illegal characters</message>
      </chars>
      <iban>
         <code>202</code>
         <message>IBAN Check digit not correct</message>
      </iban>
      <account>
         <code>002</code>
         <message>Account Number check digit is correct</message>
      </account>
      <structure>
         <code>005</code>
         <message>IBAN structure is correct</message>
      </structure>
      <length>
         <code>003</code>
         <message>IBAN Length is correct</message>
      </length>
      <country_support>
         <code>007</code>
         <message>Country supports IBAN standard</message>
      </country_support>
   </validations>
   <errors/>
</result>

Responses to account errors

One entry in errors, the other three objects empty:

{
   "bank_data": {},
   "sepa_data": {},
   "validations": {},
   "errors": [
      {
         "code": "301",
         "message": "API Key is invalid"
      }
   ]
}

{
   "bank_data": {},
   "sepa_data": {},
   "validations": {},
   "errors": [
      {
         "code": "302",
         "message": "Subscription expired"
      }
   ]
}

{
   "bank_data": {},
   "sepa_data": {},
   "validations": {},
   "errors": [
      {
         "code": "303",
         "message": "No queries available"
      }
   ]
}

{
   "bank_data": {},
   "sepa_data": {},
   "validations": {},
   "errors": [
      {
         "code": "304",
         "message": "You have no access to this API"
      }
   ]
}

{
   "bank_data": {},
   "sepa_data": {},
   "validations": {},
   "errors": [
      {
         "code": "305",
         "message": "IP Address not allowed"
      }
   ]
}

<?xml version="1.0"?>
<result>
   <bank_data/>
   <sepa_data/>
   <validations/>
   <errors>
      <error>
         <code>301</code>
         <message>API Key is invalid</message>
      </error>
   </errors>
</result>

XML schema of the response: iban-validation-api-v4.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:element name="result">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="bank_data">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="bic" type="xs:string" minOccurs="0"/>
              <xs:element name="branch" type="xs:string" minOccurs="0"/>
              <xs:element name="bank" type="xs:string" minOccurs="0"/>
              <xs:element name="address" type="xs:string" minOccurs="0"/>
              <xs:element name="city" type="xs:string" minOccurs="0"/>
              <xs:element name="state" type="xs:string" minOccurs="0"/>
              <xs:element name="zip" type="xs:string" minOccurs="0"/>
              <xs:element name="phone" type="xs:string" minOccurs="0"/>
              <xs:element name="fax" type="xs:string" minOccurs="0"/>
              <xs:element name="www" type="xs:string" minOccurs="0"/>
              <xs:element name="email" type="xs:string" minOccurs="0"/>
              <xs:element name="country" type="xs:string" minOccurs="0"/>
              <xs:element name="country_iso" type="xs:string" minOccurs="0"/>
              <xs:element name="account" type="xs:string" minOccurs="0"/>
              <xs:element name="bank_code" type="xs:string" minOccurs="0"/>
              <xs:element name="branch_code" type="xs:string" minOccurs="0"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="sepa_data">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="SCT" type="xs:string" minOccurs="0"/>
              <xs:element name="SCI" type="xs:string" minOccurs="0"/>
              <xs:element name="SCI_TIPS" type="xs:string" minOccurs="0"/>
              <xs:element name="SDD" type="xs:string" minOccurs="0"/>
              <xs:element name="COR1" type="xs:string" minOccurs="0"/>
              <xs:element name="B2B" type="xs:string" minOccurs="0"/>
              <xs:element name="SCC" type="xs:string" minOccurs="0"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="validations">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="chars" type="check" minOccurs="0"/>
              <xs:element name="iban" type="check" minOccurs="0"/>
              <xs:element name="account" type="check" minOccurs="0"/>
              <xs:element name="structure" type="check" minOccurs="0"/>
              <xs:element name="length" type="check" minOccurs="0"/>
              <xs:element name="country_support" type="check" minOccurs="0"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="errors">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="error" type="check" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:complexType name="check">
    <xs:sequence>
      <xs:element name="code" type="xs:string"/>
      <xs:element name="message" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

Result codes

Each check answers with one success code or one failure code. Success codes start with 0, failure codes with 2.

Account errors

Returned in errors when the request itself is refused. No validation is performed.

Handling errors

What each outcome means for your code. Validation results are deterministic for a given IBAN, so there is never a reason to resend one; bank data does change over time, so if you cache responses, give the cache a limited lifetime.

Reading the result

• An IBAN is valid when iban is 001, length 003, structure 005, chars 006, country_support 007 and account is 002 or 004.
• 004 means the national account check digit is not verified for that bank or country; it is not a failure. Countries with an account check are marked on the IBAN structure & examples page; within those countries some banks have no published check method.
• A valid IBAN can still come back with no bank: the bank identifier is not in our directory. bic and bank are then null and the SEPA flags are NO. Decide in your code whether that is acceptable for the payment.
• Act on codes, not messages. Messages are English text and may change; the 203 message already varies by country.
• A 2xx code in one check does not stop the others: the response always carries all six results, so a mistyped IBAN can report 202 and 205 together.

Checking your balance

The services endpoint returns every service active on your account with its remaining queries and expiry date, the same information as My Services. Poll it from your monitoring to catch a low balance before the API starts answering 303. It takes the same api_key and format parameters and does not use a query.

The response, shortened to the IBAN Suite entry (the endpoint lists every service on your account, one object each):

{
   "services": [
      {
         "service_name": "IBAN SUITE (50,000)",
         "credits": 19981,
         "expiry_date": "2027-07-11",
         "service_expired": 0
      }
   ],
   "errors": []
}

<?xml version="1.0"?>
<result>
   <services>
      <service>
         <service_name>IBAN SUITE (50,000)</service_name>
         <credits>19981</credits>
         <expiry_date>2027-07-11</expiry_date>
         <service_expired>0</service_expired>
      </service>
   </services>
   <errors/>
</result>

Without format the body is empty. errors works as on the validation endpoint: 301 for a wrong key, with services empty.

Rate limits and queries

• The shared API accepts up to 20 requests per second. A short burst of a few dozen requests above that rate is absorbed; beyond it every request is rejected with HTTP 429 Too Many Requests and a small HTML body. A rejected request never reaches the API: it is not processed and not charged. Acceptance resumes as soon as your rate drops below the limit, so wait a moment and resend; keep the sending rate at or below 20 per second with a queue or a token bucket. If several processes send requests, apply the limit to their total.
• Each processed request, whether the IBAN is valid or not, uses one query from your IBAN Suite balance. Account errors (301–305) do not use a query.
• Need more throughput? A dedicated API server is available for your account with no per-second limit, on its own hostname. Contact support with your expected volume.

Glossary