{ "openapi": "3.1.0", "info": { "title": "IBAN Validation API", "version": "4", "summary": "Validate an IBAN in six independent checks, identify the issuing bank and report its SEPA reachability.", "description": "Part of the IBAN Suite service of IBAN.com. One request validates an IBAN in six independent checks\n(characters, check digits, length, structure, national account check digit, country support), identifies\nthe issuing bank and branch with its BIC and address, and reports the bank's SEPA scheme reachability.\nEvery check comes back as its own coded result.\n\nFull documentation with recorded examples: https://developer.iban.com/validation-api\n\nThe HTTP status is 200 for every processed request, whether the IBAN is valid or not and also for account\nerrors (wrong key, expired service, no queries, no access, address not allowed): the outcome is in the\nresponse body. Each processed request uses one query from the IBAN Suite balance; account errors use none.\nThe 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/v4", "description": "Production. There is no separate sandbox; test requests use queries like any other request." } ], "tags": [ { "name": "Validation", "description": "IBAN validation, bank identification and SEPA reachability." }, { "name": "Account", "description": "Services on the account and their remaining queries." } ], "paths": { "/iban/": { "post": { "tags": [ "Validation" ], "operationId": "validateIban", "summary": "Validate 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. Returns the same response as the GET form.\n", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/ValidationRequest" }, "examples": { "basic": { "summary": "The registry example for France", "value": { "api_key": "YOUR_API_KEY", "format": "json", "iban": "FR7630006000011234567890189" } }, "with_options": { "summary": "With SEPA Instant reachability and transliteration", "value": { "api_key": "YOUR_API_KEY", "format": "json", "iban": "FR7630006000011234567890189", "sci": "1", "sci_tips": "1", "translit": "1" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/ValidationResult" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "Validation" ], "operationId": "validateIbanGet", "summary": "Validate 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/iban" }, { "$ref": "#/components/parameters/sci" }, { "$ref": "#/components/parameters/sci_tips" }, { "$ref": "#/components/parameters/translit" } ], "responses": { "200": { "$ref": "#/components/responses/ValidationResult" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/services/": { "get": { "tags": [ "Account" ], "operationId": "getServices", "summary": "List the services on the account with their remaining queries", "description": "Every service on the account with its remaining queries and expiry date, the same information as\n*My Services* in the client area. Takes the same `api_key` and `format` parameters as the validation\nendpoint and does not use a query. Poll it from your monitoring to catch a low balance before the\nvalidation endpoint starts answering 303.\n", "security": [ { "ApiKeyQuery": [] } ], "parameters": [ { "$ref": "#/components/parameters/format" } ], "responses": { "200": { "description": "The HTTP status is 200 in every case. With a wrong key `services` is empty and `errors` carries\ncode 301. Without `format` the body is empty (zero bytes, `text/html`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServicesResponse" }, "examples": { "services": { "summary": "The IBAN Suite entry of a client account (recorded 9 Oct 2026; the other services on the account left out)", "value": { "services": [ { "service_name": "IBAN SUITE (Unlimited)", "credits": "Unlimited", "expiry_date": "2027-06-01", "service_expired": 0 } ], "errors": [] } }, "wrong_key": { "summary": "Wrong key (recorded 9 Oct 2026)", "value": { "services": [], "errors": [ { "code": "301", "message": "API Key is invalid" } ] } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ServicesResponse" } } } }, "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 `ValidationRequest`). A key restricted to certain\nIP addresses under *Settings* answers 305 from any other address.\n" } }, "parameters": { "format": { "name": "format", "in": "query", "required": true, "description": "Response format, lower case: `json` or `xml`. Sets the response `Content-Type` to `application/json`\nor `application/xml`. Any other value (`JSON` in upper case included) or a missing parameter gives a\n200 with an empty body.\n", "schema": { "type": "string", "enum": [ "json", "xml" ] }, "example": "json" }, "iban": { "name": "iban", "in": "query", "required": true, "description": "The IBAN to validate, up to 100 characters. Letters are upper-cased. Any character that is not A–Z or\n0–9 (space, hyphen, tab, line break…) sets the `chars` check to 206; the characters are then removed\nand the remaining checks run on what is left, so `FR76 3000 6000 0112 3456 7890 189` still validates\nand identifies the bank. Send the IBAN without separators to get 006.\n", "schema": { "type": "string", "maxLength": 100 }, "example": "FR7630006000011234567890189" }, "sci": { "name": "sci", "in": "query", "required": false, "description": "`1` adds `SCI` to `sepa_data`: whether the identified bank is reachable for SEPA Instant Credit\nTransfer through EBA RT1. Any other value, or the parameter missing, leaves the field out.\n", "schema": { "type": "string" }, "example": "1" }, "sci_tips": { "name": "sci_tips", "in": "query", "required": false, "description": "`1` adds `SCI_TIPS` to `sepa_data`: SEPA Instant reachability through the Eurosystem TIPS service.\nAny other value, or the parameter missing, leaves the field out.\n", "schema": { "type": "string" }, "example": "1" }, "translit": { "name": "translit", "in": "query", "required": false, "description": "`1` transliterates `bank`, `address` and `city` to plain Latin letters (Vöckla → Vockla,\nHauptstraße → Hauptstrasse) for SEPA payment files that reject local characters. Any other value,\nor the parameter missing, returns the names as held in the directory.\n", "schema": { "type": "string" }, "example": "1" } }, "responses": { "ValidationResult": { "description": "Returned for every processed request. Four objects, always in this order: `bank_data`, `sepa_data`,\n`validations`, `errors`.\n\n- Request accepted: `validations` holds all six checks, `errors` is empty. Whether the IBAN is valid\n is read from the codes (success codes start with 0, failure codes with 2), not from the HTTP status.\n- Account error: `errors` holds one entry with code 301–305 and the other three objects are empty.\n- Request not understood (`iban`, `api_key` or `format` missing, or `format` not exactly `json` or\n `xml`): the body is **empty** (zero bytes, `Content-Type: text/html; charset=UTF-8`). Check for an\n empty body before parsing.\n\nThe media type follows the `format` parameter, not the `Accept` header.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" }, "examples": { "valid": { "summary": "Valid IBAN, bank identified (recorded 7 Oct 2026)", "value": { "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": [] } }, "check_digit_failed": { "summary": "Check digits changed from 76 to 77 — no bank lookup, SEPA flags NO (recorded 7 Oct 2026)", "value": { "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": [] } }, "with_sci": { "summary": "`sci=1` on GB33BUKB20201555555555: SCI inserted after SCT (recorded 7 Oct 2026)", "value": { "bank_data": { "bic": "BUKBGB22XXX", "branch": "CHELTENHAM", "bank": "BARCLAYS BANK UK PLC", "address": " ", "city": "Leicester", "state": null, "zip": "LE87 2BB", "phone": null, "fax": null, "www": null, "email": null, "country": "United Kingdom", "country_iso": "GB", "account": "55555555", "bank_code": "BUKB", "branch_code": "202015" }, "sepa_data": { "SCT": "YES", "SCI": "NO", "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": [] } }, "account_error": { "summary": "Wrong key (recorded 7 Oct 2026); 302–305 have the same shape", "value": { "bank_data": {}, "sepa_data": {}, "validations": {}, "errors": [ { "code": "301", "message": "API Key is invalid" } ] } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ValidationResponse" }, "examples": { "valid": { "summary": "`format=xml` for GB33BUKB20201555555555 (recorded 7 Oct 2026)", "description": "The same response as the JSON example `with_sci` without the `sci` option. Element order as\nsent by the API (it differs from the JSON member order inside `validations`); a field without\na value is an empty element. Verbatim, indented:\n\n```xml\n\n\n \n BUKBGB22XXX\n CHELTENHAM\n BARCLAYS BANK UK PLC\n
\n Leicester\n \n LE87 2BB\n \n \n \n \n United Kingdom\n GB\n 55555555\n BUKB\n 202015\n \n \n YES\n YES\n YES\n YES\n NO\n \n \n \n 006\n IBAN does not contain illegal characters\n \n \n 001\n IBAN Check digit is correct\n \n \n 002\n Account Number check digit is correct\n \n \n 005\n IBAN structure is correct\n \n \n 003\n IBAN Length is correct\n \n \n 007\n Country supports IBAN standard\n \n \n \n\n```\n", "value": { "bank_data": { "bic": "BUKBGB22XXX", "branch": "CHELTENHAM", "bank": "BARCLAYS BANK UK PLC", "address": " ", "city": "Leicester", "state": null, "zip": "LE87 2BB", "phone": null, "fax": null, "www": null, "email": null, "country": "United Kingdom", "country_iso": "GB", "account": "55555555", "bank_code": "BUKB", "branch_code": "202015" }, "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": [] } } } } } }, "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" } } } }, "ServerError": { "description": "Empty `text/html` body. Seen for a malformed request (an array-style parameter such as `iban[]`); for\nanything else it is a temporary problem — retry with increasing delays. A request that got no answer\nmay still have been processed, so a retry costs at most one extra query.\n", "content": { "text/html": { "schema": { "type": "string" } } } } }, "schemas": { "ValidationRequest": { "type": "object", "required": [ "api_key", "format", "iban" ], "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" ], "description": "Response format, lower case. Any other value gives a 200 with an empty body." }, "iban": { "type": "string", "maxLength": 100, "description": "The IBAN to validate. Letters are upper-cased; separators set `chars` to 206 and are then removed.", "examples": [ "FR7630006000011234567890189", "FR76 3000 6000 0112 3456 7890 189" ] }, "sci": { "type": "string", "description": "`1` adds `SCI` (SEPA Instant through EBA RT1) to `sepa_data`; any other value or absence leaves it out.", "examples": [ "1" ] }, "sci_tips": { "type": "string", "description": "`1` adds `SCI_TIPS` (SEPA Instant through TIPS) to `sepa_data`; any other value or absence leaves it out.", "examples": [ "1" ] }, "translit": { "type": "string", "description": "`1` transliterates `bank`, `address` and `city` to plain Latin letters; any other value or absence returns them as held.", "examples": [ "1" ] } } }, "ValidationResponse": { "type": "object", "required": [ "bank_data", "sepa_data", "validations", "errors" ], "description": "Always the four objects, in this order. On an account error `bank_data`, `sepa_data` and `validations`\nare empty objects (empty elements in XML) and `errors` holds one entry.\n", "properties": { "bank_data": { "$ref": "#/components/schemas/BankData" }, "sepa_data": { "$ref": "#/components/schemas/SepaData" }, "validations": { "$ref": "#/components/schemas/Validations" }, "errors": { "type": "array", "description": "Empty when the request was accepted; one entry on an account error.", "items": { "$ref": "#/components/schemas/AccountError" }, "xml": { "wrapped": true } } }, "xml": { "name": "result" } }, "BankData": { "type": "object", "description": "`country`, `country_iso`, `account` and `bank_code` are read from the IBAN itself and are filled whenever\nthe country is known and the IBAN parses, even when a check fails; `branch_code` is read the same way but\nis empty for countries whose IBAN has no branch part. The other eleven come from the bank directory and are filled only when a bank is identified, which is attempted only when the\ncheck digits (`iban` 001) and the length (`length` 003) are correct. A field without a value is `null`\nin JSON (an empty string may also be returned; treat both alike) and an empty element in XML. Empty\nobject on an account error.\n", "properties": { "bic": { "type": [ "string", "null" ], "maxLength": 11, "description": "BIC of the issuing bank or branch." }, "branch": { "type": [ "string", "null" ], "maxLength": 256, "description": "Branch name, when the directory has one." }, "bank": { "type": [ "string", "null" ], "maxLength": 256, "description": "Name of the bank or institution that issued the IBAN." }, "address": { "type": [ "string", "null" ], "maxLength": 128, "description": "Street address of the bank or branch." }, "city": { "type": [ "string", "null" ], "maxLength": 128, "description": "City of the bank or branch." }, "state": { "type": [ "string", "null" ], "maxLength": 128, "description": "State or region, where the country uses one." }, "zip": { "type": [ "string", "null" ], "maxLength": 11, "description": "Postal code." }, "phone": { "type": [ "string", "null" ], "description": "Telephone number, when the directory has one." }, "fax": { "type": [ "string", "null" ], "description": "Fax number." }, "www": { "type": [ "string", "null" ], "description": "Web site." }, "email": { "type": [ "string", "null" ], "description": "Contact e-mail address." }, "country": { "type": [ "string", "null" ], "maxLength": 32, "description": "Country name, from the IBAN prefix (France)." }, "country_iso": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-2 code, from the IBAN prefix (FR, GB, DE…)." }, "account": { "type": [ "string", "null" ], "description": "Domestic account number part of the BBAN, as the country defines it. May contain letters and leading zeros — a string." }, "bank_code": { "type": [ "string", "null" ], "description": "National bank identifier taken from the BBAN: BLZ, sort code, ABI, four-letter code (GB, NL, BG…). A string." }, "branch_code": { "type": [ "string", "null" ], "description": "Branch identifier taken from the BBAN. Filled for the 28 countries whose IBAN carries a branch code:\nAD AL BA BG BR CY DJ EG ES FR GB GR IE IL IT LY MC MR MT MU PT SD SK SM ST TL TN XK; empty for the other 61 (DE, AT, NL, BE, CH, PL, SE…).\n" } } }, "SepaData": { "type": "object", "description": "Scheme reachability of the identified bank, `YES` or `NO`; all `NO` when no bank is identified. The five\nstandard flags are always present; `SCI` and `SCI_TIPS` only with `sci=1` / `sci_tips=1`, placed right\nafter `SCT`. Empty object on an account error.\n", "properties": { "SCT": { "$ref": "#/components/schemas/YesNo", "description": "SEPA Credit Transfer." }, "SCI": { "$ref": "#/components/schemas/YesNo", "description": "SEPA Instant Credit Transfer through EBA RT1 (only with `sci=1`)." }, "SCI_TIPS": { "$ref": "#/components/schemas/YesNo", "description": "SEPA Instant Credit Transfer through TIPS (only with `sci_tips=1`)." }, "SDD": { "$ref": "#/components/schemas/YesNo", "description": "SEPA Direct Debit (Core)." }, "COR1": { "$ref": "#/components/schemas/YesNo", "description": "SEPA Direct Debit COR1 option." }, "B2B": { "$ref": "#/components/schemas/YesNo", "description": "SEPA Direct Debit Business-to-Business." }, "SCC": { "$ref": "#/components/schemas/YesNo", "description": "SEPA Card Clearing." } } }, "YesNo": { "type": "string", "enum": [ "YES", "NO" ] }, "Validations": { "type": "object", "description": "One member per check, each with a three-character `code` (leading zero kept: `\"006\"`, compare as a\nstring) and an English `message` that may change — act on the code. The member order differs between\nJSON and XML, so address them by name. All six are present whenever the request was accepted; empty\nobject on an account error.\n", "properties": { "chars": { "allOf": [ { "$ref": "#/components/schemas/Check" }, { "properties": { "code": { "enum": [ "006", "206" ] } } } ], "description": "006 no illegal characters; 206 illegal characters (removed before the other checks)." }, "iban": { "allOf": [ { "$ref": "#/components/schemas/Check" }, { "properties": { "code": { "enum": [ "001", "202" ] } } } ], "description": "001 check digits correct; 202 check digits not correct." }, "length": { "allOf": [ { "$ref": "#/components/schemas/Check" }, { "properties": { "code": { "enum": [ "003", "203" ] } } } ], "description": "003 length correct; 203 length not correct — the message names the country and the expected length." }, "structure": { "allOf": [ { "$ref": "#/components/schemas/Check" }, { "properties": { "code": { "enum": [ "005", "205" ] } } } ], "description": "005 structure correct; 205 structure not correct." }, "account": { "allOf": [ { "$ref": "#/components/schemas/Check" }, { "properties": { "code": { "enum": [ "002", "004", "201" ] } } } ], "description": "002 national account check digit correct; 004 not performed for this bank or branch (not a failure); 201 not correct." }, "country_support": { "allOf": [ { "$ref": "#/components/schemas/Check" }, { "properties": { "code": { "enum": [ "007", "207" ] } } } ], "description": "007 country supports the IBAN standard; 207 it does not." } } }, "Check": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "pattern": "^[0-9]{3}$", "description": "Three-character result code; success codes start with 0, failure codes with 2." }, "message": { "type": "string", "description": "English text for the code; may change." } } }, "AccountError": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "301", "302", "303", "304", "305" ], "description": "301 API key is invalid · 302 subscription expired · 303 no queries available · 304 no access to this\nAPI · 305 IP address not allowed. None of them uses a query.\n" }, "message": { "type": "string", "examples": [ "API Key is invalid", "Subscription expired", "No queries available", "You have no access to this API", "IP Address not allowed" ] } }, "xml": { "name": "error" } }, "ServicesResponse": { "type": "object", "required": [ "services", "errors" ], "properties": { "services": { "type": "array", "description": "Every service on the account; empty with a wrong key.", "items": { "$ref": "#/components/schemas/Service" }, "xml": { "wrapped": true } }, "errors": { "type": "array", "description": "Empty when the key was accepted; one entry with code 301 for a wrong key.", "items": { "$ref": "#/components/schemas/AccountError" }, "xml": { "wrapped": true } } }, "xml": { "name": "result" } }, "Service": { "type": "object", "required": [ "service_name", "credits", "expiry_date", "service_expired" ], "properties": { "service_name": { "type": "string", "description": "Name as shown under *My Services*. The IBAN Suite entry carries the plan size in brackets (`IBAN SUITE (50,000)`, `IBAN SUITE (Unlimited)`): match on the prefix `IBAN SUITE`." }, "credits": { "type": [ "integer", "string" ], "description": "Remaining queries. Services without a quota return the string `Unlimited` instead of a number, so test the type before comparing.", "examples": [ 52, "Unlimited" ] }, "expiry_date": { "type": "string", "format": "date", "description": "Expiry date of the service, `YYYY-MM-DD`. Requests after this date get 302." }, "service_expired": { "type": "integer", "enum": [ 0, 1 ], "description": "1 when the service has expired." } }, "xml": { "name": "service" } } } } }