IBAN Calculation API

Part of the IBAN Suite service. One request turns a domestic bank code and account number into the IBAN, verifies the national check digits where the country has them, and identifies the bank with its BIC and address. 57 countries are supported; each has its own set of input fields, listed in the countries table together with a working example and the IBAN it produces.

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, and the parameters may be split between them.
• The HTTP status is 200 for every processed request, whether the IBAN could be calculated or not; the outcome is in the response body. The only other status is 429 when the rate limit is exceeded; that response is a short HTML page, not JSON or XML, so check the status before parsing.
• A successful response is a flat object with the IBAN and the bank details. A failed one is a single error member with a message. Test for error first.
• Responses are UTF-8. The Content-Type follows the format parameter.
• Submitted account numbers 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/calc-api.php" -d api_key=YOUR_API_KEY -d format=json -d country=FR -d bankcode=30006 -d branch=00001 -d account=1234567890189

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 are refused.
• 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

api_key and country are always needed, and account for every country except when a RIB is sent. Which of the others a country uses, and what goes into them, is in the countries table.

Countries and required fields

Every example below was run against the API and returned the IBAN shown. Copy the query, add api_key and format, and you have a working request for that country. Where a field says up to, shorter values are padded with leading zeros.

A country not in this table (for example AL, BG, RO, TR or XK) is answered with Country or Bank not supported or Bank Code not found. Use the IBAN Validation API to check IBANs from those countries.

Example request

Every example calculates the same French IBAN from bank code 30006, branch 00001 and account 1234567890189; the response is shown in the next section. Replace YOUR_API_KEY with the key from API Access.

curl "https://api.iban.com/clients/api/calc-api.php" \
  -d api_key=YOUR_API_KEY \
  -d format=json \
  -d country=FR \
  -d bankcode=30006 \
  -d branch=00001 \
  -d account=1234567890189

<?php
$ch = curl_init('https://api.iban.com/clients/api/calc-api.php');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'api_key'  => 'YOUR_API_KEY',
        'format'   => 'json',
        'country'  => 'FR',
        'bankcode' => '30006',
        'branch'   => '00001',
        'account'  => '1234567890189',
    ]),
]);
$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/calc-api.php', data={
    'api_key': 'YOUR_API_KEY',
    'format': 'json',
    'country': 'FR',
    'bankcode': '30006',
    'branch': '00001',
    'account': '1234567890189',
})
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',
  country: 'FR',
  bankcode: '30006',
  branch: '00001',
  account: '1234567890189',
});

fetch('https://api.iban.com/clients/api/calc-api.php', { 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 IbanCalc {
    public static void main(String[] args) throws Exception {
        String body = "api_key=YOUR_API_KEY&format=json&country=FR&bankcode=30006&branch=00001&account=1234567890189";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.iban.com/clients/api/calc-api.php"))
            .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",
    ["country"]  = "FR",
    ["bankcode"] = "30006",
    ["branch"]   = "00001",
    ["account"]  = "1234567890189",
});
var response = await client.PostAsync("https://api.iban.com/clients/api/calc-api.php", 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"},
		"country":  {"FR"},
		"bankcode": {"30006"},
		"branch":   {"00001"},
		"account":  {"1234567890189"},
	}
	resp, err := http.PostForm("https://api.iban.com/clients/api/calc-api.php", 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))
}

The same request with a RIB

For France the three fields can be replaced by the complete RIB:

The response is the same except that the rib and zip fields are not included.

Response

A flat object. The first three fields are the ones to read: iban, bic and bank. The response to the example request:

{
   "iban": "FR7630006000011234567890189",
   "rib": "30006000011234567890189",
   "bic": "AGRIFRPP",
   "bank": "CREDIT AGRICOLE S A",
   "address": "12 PL DES ETATS UNIS",
   "city": "MONTROUGE CEDEX",
   "zip": "92127",
   "country": "FR"
}

<?xml version="1.0" encoding="utf-8"?>
<result>
   <iban>FR7630006000011234567890189</iban>
   <rib>30006000011234567890189</rib>
   <bic>AGRIFRPP</bic>
   <bank>CREDIT AGRICOLE S A</bank>
   <address>12 PL DES ETATS UNIS</address>
   <city>MONTROUGE CEDEX</city>
   <zip>92127</zip>
   <country>FR</country>
</result>

Fields

Which fields come back depends on the country, because each national directory holds different data. Five fields are always there; the rest are listed with the countries that return them. A field without a value is an empty string in JSON and an empty element in XML; treat null the same way.

A country with more fields

The United Kingdom returns the normalised sort code and account number and the branch name:

{
   "iban": "GB90ABBY09012793496333",
   "account": "93496333",
   "sort_code": "090127",
   "bank": "Santander UK plc",
   "branch": "SANTANDER BANK ACCOUNT",
   "bic": "ABBYGB2LXXX",
   "address": "Santander Sapien6 - SR43 4ET Santander Domestic Payments ",
   "city": "Sunderland",
   "zip": "SR43 4ET",
   "country": "GB",
   "phone": "0800 0851785"
}

Response to a failed calculation

One member only. The example is Belgium with wrong check digits:

{
   "error": "Account number is invalid"
}

<?xml version="1.0" encoding="utf-8"?>
<error>Account number is invalid</error>

A wrong or missing key is answered the same way, with the message API Key is invalid (in XML without the declaration line).

Error messages

Messages are English text and differ by country; there are no numeric codes. Act on the presence of error, and show the message to the user. The messages recorded during testing, grouped by meaning:

Handling errors

What each outcome means for your code. A calculation is deterministic for a given input, 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 returned only when the bank identifier was found in the directory, so a response with iban always carries bank; bic is empty for the few institutions that have none. The IBAN check digits are computed by the API; every returned IBAN passes the ISO 13616 check.
• The national account check digit is verified before the IBAN is built for BE, CZ, DE, DK, EE, ES, FI, FO, FR, GB, GL, HR, HU, NO, PL, PT, SE, SI, SK. In Germany and Denmark the rule depends on the bank: accounts of a bank without a published check-digit method are accepted as sent. For the other countries the account number is checked for length and characters and taken as sent.
• Read the country from the IBAN, not from the country field, which is not present for every country.
• bic is 8 or 11 characters. If your system needs 11, append XXX to an 8-character value.
• Bank code, branch and account are normalised before the calculation: spaces and dashes are removed, numeric fields are padded with leading zeros, and for Belgium missing check digits are computed. The IBAN tells you exactly what was used.
• To check an IBAN you already have, use the IBAN Validation API; it also reports SEPA reachability, which this API does not.

Checking your balance

Each calculation uses one query from your IBAN Suite balance, the same balance as the Validation API. The services endpoint returns every service active on your account with its remaining queries and expiry date; it takes api_key and format and does not use a query. It is documented with a sample response on the Validation API page.

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.
• 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