{ "openapi": "3.1.0", "info": { "title": "IBAN Calculation API", "version": "1", "summary": "Turn a domestic bank code and account number into the IBAN, with the bank's BIC and address.", "description": "Part of the IBAN Suite service of IBAN.com. One request turns a domestic bank code and account number into\nthe IBAN, verifies the national check digits where the country has them, and identifies the bank with its\nBIC and address. 57 countries are supported; each has its own set of input fields, listed per country in\nthe documentation together with a working example.\n\nFull documentation with recorded examples and the countries table: https://developer.iban.com/calculation-api\n\nThe HTTP status is 200 for every processed request, whether the IBAN could be calculated or not: a success\nis a flat object with `iban`, `bic`, `bank`…; a failure is a single `error` member with an English message\n(there are no numeric codes). Each calculation uses one query from the IBAN Suite balance, the same balance\nas the IBAN Validation API. The shared API accepts up to 20 requests per second.\n", "termsOfService": "https://www.iban.com/terms", "license": { "name": "Proprietary — IBAN.com Terms & Conditions", "url": "https://www.iban.com/terms" }, "contact": { "name": "IBAN.com support", "url": "https://clients.iban.com/support" } }, "servers": [ { "url": "https://api.iban.com/clients/api", "description": "Production. There is no separate sandbox; test requests use queries like any other request." } ], "tags": [ { "name": "Calculation", "description": "IBAN calculation from the domestic account identifiers." } ], "paths": { "/calc-api.php": { "post": { "tags": [ "Calculation" ], "operationId": "calculateIban", "summary": "Calculate an IBAN (POST)", "description": "Parameters as an `application/x-www-form-urlencoded` body, the key included. Preferred in production:\nthe key travels in the request body instead of the URL. The parameters may also be split between the\nbody and the query string. Returns the same response as the GET form.\n", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CalculationRequest" }, "examples": { "FR": { "summary": "France — bank code, branch, account (recorded 8 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country": "FR", "bankcode": "30006", "branch": "00001", "account": "1234567890189" } }, "FR_rib": { "summary": "France — the whole RIB instead of the three fields", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country": "FR", "rib": "30006000011234567890189" } }, "GB": { "summary": "United Kingdom — sort code and account number (recorded 8 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country": "GB", "bankcode": "090127", "account": "93496333" } }, "DE": { "summary": "Germany — BLZ and Kontonummer (recorded 8 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country": "DE", "bankcode": "37010050", "account": "399509" } }, "ES": { "summary": "Spain — entidad, oficina, dígitos de control, cuenta (recorded 8 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country": "ES", "bankcode": "0081", "branch": "1731", "cd": "91", "account": "0006040912" } }, "CZ": { "summary": "Czech Republic — bank code, account prefix, account (recorded 8 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country": "CZ", "bankcode": "0100", "prefix": "51", "account": "1707230277" } }, "IS": { "summary": "Iceland — bank, account type, account, kennitala (recorded 8 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country": "IS", "bankcode": "0001", "acc_type": "12", "account": "123456", "kennitala": "3108962099" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/CalculationResult" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Calculation" ], "operationId": "calculateIbanGet", "summary": "Calculate an IBAN (GET)", "description": "The same parameters in the query string, the key included (`api_key`). Returns the same response as the\nPOST form. With GET the key is part of the URL and ends up in proxy and web-server access logs: use POST\nin production.\n", "security": [ { "ApiKeyQuery": [] } ], "parameters": [ { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/bankcode" }, { "$ref": "#/components/parameters/branch" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/cd" }, { "$ref": "#/components/parameters/prefix" }, { "$ref": "#/components/parameters/rib" }, { "$ref": "#/components/parameters/acc_type" }, { "$ref": "#/components/parameters/kennitala" } ], "responses": { "200": { "$ref": "#/components/responses/CalculationResult" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Your personal key, shown under *API Access* in the client area, as the `api_key` parameter. On a POST\nrequest it is a field of the form body instead (see `CalculationRequest`). A wrong or missing key is\nanswered with HTTP 200 and `{\"error\": \"API Key is invalid\"}`.\n" } }, "parameters": { "format": { "name": "format", "in": "query", "required": false, "description": "Response format, lower case: `json` (default when omitted) or `xml`. Any other value, `JSON` in upper\ncase included, returns an HTML *Page not found!* page with HTTP 200. For BR, CY, EG, HR, IL, IS and RS\nthe response is JSON even when `xml` is requested.\n", "schema": { "type": "string", "enum": [ "json", "xml" ], "default": "json" }, "example": "json" }, "country": { "name": "country", "in": "query", "required": true, "description": "Country of the account, ISO 3166-1 alpha-2 in upper case (lower case is not accepted for most\ncountries). One of the 57 supported countries; the documentation's countries table says which fields\neach one needs. A country outside the list is answered with *Country or Bank not supported* or *Bank\nCode not found*.\n", "schema": { "$ref": "#/components/schemas/CountryCode" }, "example": "FR" }, "bankcode": { "name": "bankcode", "in": "query", "required": false, "description": "National bank identifier: BLZ, sort code, clearing number, ABI, ISPB, a 4-letter bank code… as the\ncountries table says. Spaces and dashes are removed. Not used by countries whose account number already\ncontains the bank (BA, EE, FI, HU, MA, MK, NO, RS, TN); optional for PL.\n", "schema": { "type": "string" }, "example": "30006" }, "branch": { "name": "branch", "in": "query", "required": false, "description": "Branch identifier for the countries whose account structure has one (BR, ES, FR, IL, IT, JO, MC, MR, PT, SM).", "schema": { "type": "string" }, "example": "00001" }, "account": { "name": "account", "in": "query", "required": false, "description": "Domestic account number; required for every country except when a RIB is sent. Where the countries\ntable says *up to*, a shorter value is padded with leading zeros; a field with a fixed length (GB, IE,\nNO…) must be sent complete. Keep letters where the country uses them (CH, FR, MC, IT…). Spaces are\nremoved. Send it as a string: leading zeros matter.\n", "schema": { "type": "string" }, "example": "1234567890189" }, "cd": { "name": "cd", "in": "query", "required": false, "description": "National check digits, always two digits (`07`, not `7`): Spain (dígitos de control) and Portugal (NIB\ncheck) require them; Belgium accepts them and computes them when omitted.\n", "schema": { "type": "string", "pattern": "^[0-9]{2}$" }, "example": "91" }, "prefix": { "name": "prefix", "in": "query", "required": false, "description": "Account prefix for CZ and SK (předčíslí / predčíslie), up to 6 digits. Omit when the account has none; zeros are padded.", "schema": { "type": "string" }, "example": "51" }, "rib": { "name": "rib", "in": "query", "required": false, "description": "France only: the complete 23-character RIB (bank 5, branch 5, account 11, key 2) instead of `bankcode`,\n`branch` and `account`. Spaces are removed; when `rib` is sent the three fields are ignored. For Monaco\nsend the three fields.\n", "schema": { "type": "string" }, "example": "30006000011234567890189" }, "acc_type": { "name": "acc_type", "in": "query", "required": false, "description": "Iceland only — account type (höfuðbók), 2 digits, e.g. `12` or `26`.", "schema": { "type": "string" }, "example": "12" }, "kennitala": { "name": "kennitala", "in": "query", "required": false, "description": "Iceland only — national identification number of the account holder, 10 digits; required for Iceland, it becomes the last ten characters of the IBAN.", "schema": { "type": "string" }, "example": "3108962099" } }, "responses": { "CalculationResult": { "description": "Returned for every processed request.\n\n- Calculated: a flat object with the IBAN and the bank details (`CalculationSuccess`). Which fields come\n back depends on the country; `iban`, `bic`, `bank`, `address` and `city` are always there.\n- Not calculated: one member `error` with an English message (`CalculationError`). Test for `error`\n first. Messages differ by country; the documentation lists the recorded ones grouped by meaning.\n- `format` not `json` or `xml`: the body is an HTML page (*Page not found!*).\n\nThe media type follows the `format` parameter (JSON when omitted), not the `Accept` header. In XML a\nsuccess is a `` element and a failure an `` element (for a wrong key without the XML\ndeclaration line).\n", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CalculationSuccess" }, { "$ref": "#/components/schemas/CalculationError" } ] }, "examples": { "FR": { "summary": "France (recorded 8 Oct 2026)", "value": { "iban": "FR7630006000011234567890189", "rib": "30006000011234567890189", "bic": "AGRIFRPP", "bank": "CREDIT AGRICOLE S A", "address": "12 PL DES ETATS UNIS", "city": "MONTROUGE CEDEX", "zip": "92127", "country": "FR" } }, "GB": { "summary": "United Kingdom — normalised sort code and account, branch name, phone (recorded 8 Oct 2026)", "value": { "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" } }, "check_digits_wrong": { "summary": "Belgium with wrong check digits (recorded 8 Oct 2026)", "value": { "error": "Account number is invalid" } }, "wrong_key": { "summary": "Wrong or missing key (recorded 8 Oct 2026)", "value": { "error": "API Key is invalid" } } } }, "application/xml": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CalculationSuccess" }, { "$ref": "#/components/schemas/CalculationError" } ] }, "examples": { "AT": { "summary": "Austria, `format=xml` (recorded 8 Oct 2026)", "description": "Verbatim:\n\n```xml\nAT401200052700357958BKAUATWWXXXUniCredit Bank Austria AG
Rothschildplatz 1
Wien1020AT\n```\n", "value": { "iban": "AT401200052700357958", "bic": "BKAUATWWXXX", "bank": "UniCredit Bank Austria AG", "address": "Rothschildplatz 1", "city": "Wien", "zip": "1020", "country": "AT", "phone": "", "fax": "", "email": "", "website": "" } }, "error": { "summary": "Failure in XML (recorded 8 Oct 2026)", "description": "Verbatim: `Illegal characters submitted`\n", "value": { "error": "Illegal characters submitted" } } } }, "text/html": { "schema": { "type": "string" }, "examples": { "bad_format": { "summary": "`format` is not `json` or `xml` (recorded 8 Oct 2026)", "value": "Page not found!" } } } } }, "RateLimited": { "description": "More than 20 requests per second. Rejected by the web server before reaching the API: not processed,\nnot charged; the body is a small HTML page, there is no `Retry-After` header. Wait a moment and resend.\n", "content": { "text/html": { "schema": { "type": "string" } } } } }, "schemas": { "CountryCode": { "type": "string", "description": "ISO 3166-1 alpha-2, upper case — one of the 57 supported countries.", "enum": [ "AD", "AE", "AT", "BA", "BE", "BH", "BR", "CH", "CY", "CZ", "DE", "DK", "DO", "EE", "EG", "ES", "FI", "FO", "FR", "GB", "GL", "GR", "GT", "HR", "HU", "IE", "IL", "IS", "IT", "JO", "KW", "LI", "LT", "LU", "LV", "MA", "MC", "MD", "MK", "MR", "MT", "NL", "NO", "PK", "PL", "PT", "QA", "RS", "RU", "SA", "SE", "SI", "SK", "SM", "SV", "TN", "UA" ] }, "CalculationRequest": { "type": "object", "required": [ "api_key", "country" ], "description": "`api_key` and `country` are always needed, and `account` for every country except when a RIB is sent.\nWhich of the other fields a country uses is in the countries table of the documentation.\n", "properties": { "api_key": { "type": "string", "description": "Your personal key, shown under *API Access* in the client area.", "examples": [ "YOUR_API_KEY" ] }, "format": { "type": "string", "enum": [ "json", "xml" ], "default": "json", "description": "Response format, lower case. Any other value returns an HTML page with HTTP 200." }, "country": { "$ref": "#/components/schemas/CountryCode" }, "bankcode": { "type": "string", "description": "National bank identifier (BLZ, sort code, clearing number, ABI, ISPB, 4-letter code…); spaces and dashes removed.", "examples": [ "30006", "09-01-27", "ABNA" ] }, "branch": { "type": "string", "description": "Branch identifier (BR, ES, FR, IL, IT, JO, MC, MR, PT, SM).", "examples": [ "00001" ] }, "account": { "type": "string", "description": "Domestic account number; shorter values are padded with leading zeros where the country allows *up to* N characters. A string — leading zeros matter.", "examples": [ "1234567890189", "93496333" ] }, "cd": { "type": "string", "pattern": "^[0-9]{2}$", "description": "National check digits, two digits (ES, PT required; BE optional).", "examples": [ "91" ] }, "prefix": { "type": "string", "description": "Account prefix for CZ and SK, up to 6 digits.", "examples": [ "51" ] }, "rib": { "type": "string", "description": "France only — the 23-character RIB instead of `bankcode`, `branch` and `account`.", "examples": [ "30006000011234567890189" ] }, "acc_type": { "type": "string", "description": "Iceland only — account type, 2 digits.", "examples": [ "12" ] }, "kennitala": { "type": "string", "description": "Iceland only — national identification number, 10 digits.", "examples": [ "3108962099" ] } } }, "CalculationSuccess": { "type": "object", "required": [ "iban", "bic", "bank", "address", "city" ], "description": "A flat object. Five fields are always there; the others depend on the country's directory. A field\nwithout a value is an empty string (an empty element in XML); treat `null` the same way.\n", "properties": { "iban": { "type": "string", "description": "The calculated IBAN, without spaces. Read the country from its first two characters." }, "bic": { "type": "string", "description": "BIC of the bank or branch from the directory — 11 characters, or 8 where the directory holds the head-office BIC only (BR, FR, GT, MA, MC, MR, SE, SV, TN). Empty when the institution has no BIC." }, "bank": { "type": "string", "description": "Name of the bank or institution." }, "address": { "type": "string", "description": "Street address of the bank or branch; may be empty." }, "city": { "type": "string", "description": "City of the bank or branch." }, "zip": { "type": "string", "description": "Postal code; may be empty. Not returned for MA and TN." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 code. Returned for 38 countries only and sometimes empty — read the country from the IBAN instead." }, "branch": { "type": "string", "description": "Branch name where the directory has one (24 countries); often empty." }, "phone": { "type": [ "string", "null" ], "description": "Contact details of the bank (also `fax`, `email`, `website`); present for some countries, filled only for the United Kingdom." }, "fax": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "rib": { "type": "string", "description": "FR, MC, MR — the 23-character RIB (bank, branch, account, key). Not returned when the request used the `rib` parameter." }, "account": { "type": "string", "description": "GB (also GR, IS) — the account number as normalised by the API." }, "sort_code": { "type": "string", "description": "GB — the sort code as normalised by the API, 6 digits." }, "state": { "type": "string", "description": "IT, SM — province; may be empty." }, "currency": { "type": "string", "description": "IE — account currency from the directory." }, "details": { "type": "string", "description": "PL — reserved; empty." } }, "xml": { "name": "result" } }, "CalculationError": { "type": "object", "required": [ "error" ], "additionalProperties": false, "description": "The IBAN was not calculated. English message, wording differs by country; there are no numeric codes.", "properties": { "error": { "type": "string", "examples": [ "API Key is invalid", "Country or Bank not supported", "Required fields not submitted.", "Account number is invalid", "Bank Code not found.", "RIB is not valid" ] } } } } } }