{ "openapi": "3.1.0", "info": { "title": "Bank Suite API", "version": "1", "summary": "Validate a domestic bank code (and account number) for countries that do not use the IBAN, look a BIC up in the bank directory, and read the bank-code and account formats of a country.", "description": "Part of the Bank Suite service of IBAN.com: bank code and account number validation for countries that do\nnot use the IBAN, backed by a bank directory of 193 countries that is updated monthly. The bank code\nendpoint validates a domestic bank code (routing number, sort code, BLZ, IFSC…), optionally the account\nnumber, and returns the institution and branch behind it with BIC, LEI, address and network data. The BIC\nendpoint returns the same record for a BIC. The structure endpoint describes the bank-code and\naccount-number formats of a country, with an example and a regular expression.\n\nFull documentation with recorded examples, the supported countries and the field-value lists:\nhttps://developer.iban.com/bank-suite-api\n\nHTTP status: **200** for every processed request (the outcome is in `error.code`: 8xx and 400 describe the\ninput); **400** with result code 306/307 for a missing parameter or a bad `limit` (and 802/400 on the\nstructure endpoint); **403** (401 on the structure endpoint) for an account error (3xx); **429** above 20\nrequests per second; **500** with an empty body for a malformed parameter. In JSON the `error` member is\npresent only when something failed. Each processed request on the bank code and BIC endpoints uses one query\nfrom the Bank Suite balance.\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/banksuite", "description": "Production. There is no separate sandbox." } ], "tags": [ { "name": "Bank code", "description": "Validate a domestic bank code and account number." }, { "name": "BIC", "description": "Look a BIC up in the bank directory." }, { "name": "Structure", "description": "Bank-code and account-number formats per country." } ], "paths": { "/nid/": { "post": { "tags": [ "Bank code" ], "operationId": "validateBankCode", "summary": "Validate a bank code and account number (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/BankCodeRequest" }, "examples": { "us_routing": { "summary": "US routing number 322271627 (recorded 9 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country_iso": "US", "nid": "322271627" } }, "gb_with_account": { "summary": "UK sort code 200415 with an account number (recorded 9 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country_iso": "GB", "nid": "200415", "account": "38290008" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/BankCodeResult" }, "400": { "$ref": "#/components/responses/BankCodeBadRequest" }, "403": { "$ref": "#/components/responses/BankCodeAccountError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "Bank code" ], "operationId": "validateBankCodeGet", "summary": "Validate a bank code and account number (GET)", "description": "The same parameters in the query string, the key included (`api_key`). Use POST in production.", "security": [ { "ApiKeyQuery": [] } ], "parameters": [ { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/country_iso" }, { "$ref": "#/components/parameters/nid" }, { "$ref": "#/components/parameters/account" }, { "$ref": "#/components/parameters/limit" } ], "responses": { "200": { "$ref": "#/components/responses/BankCodeResult" }, "400": { "$ref": "#/components/responses/BankCodeBadRequest" }, "403": { "$ref": "#/components/responses/BankCodeAccountError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/bic/": { "post": { "tags": [ "BIC" ], "operationId": "lookupBic", "summary": "Look a BIC up in the bank directory (POST)", "description": "Returns the directory record of a BIC, with `national_id` carrying the bank code the BIC corresponds to. An 8-character BIC returns its head-office record.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/BicRequest" }, "examples": { "barclays": { "summary": "BARCGB22XXX (recorded 9 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "bic": "BARCGB22XXX" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/BicResult" }, "400": { "$ref": "#/components/responses/BicBadRequest" }, "403": { "$ref": "#/components/responses/BicAccountError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "get": { "tags": [ "BIC" ], "operationId": "lookupBicGet", "summary": "Look a BIC up in the bank directory (GET)", "description": "The same parameters in the query string, the key included (`api_key`). Use POST in production.", "security": [ { "ApiKeyQuery": [] } ], "parameters": [ { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/bic" }, { "$ref": "#/components/parameters/bic_limit" } ], "responses": { "200": { "$ref": "#/components/responses/BicResult" }, "400": { "$ref": "#/components/responses/BicBadRequest" }, "403": { "$ref": "#/components/responses/BicAccountError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/structure/": { "post": { "tags": [ "Structure" ], "operationId": "getStructure", "summary": "Bank-code and account-number formats of a country (POST)", "description": "Describes what a country's bank code and account number look like: local name, clearing system, an\nexample, a letter-per-position format, a regular expression, the elements and the lengths. Does not use a\nquery. Several formats may be listed (the US has the routing number, the CHIPS ID and the CHIPS\nuniversal ID).\n", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/StructureRequest" }, "examples": { "gb": { "summary": "United Kingdom (recorded 9 Oct 2026)", "value": { "api_key": "YOUR_API_KEY", "format": "json", "country_iso": "GB" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/StructureResult" }, "400": { "$ref": "#/components/responses/StructureBadRequest" }, "401": { "$ref": "#/components/responses/StructureAccountError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "tags": [ "Structure" ], "operationId": "getStructureGet", "summary": "Bank-code and account-number formats of a country (GET)", "description": "The same parameters in the query string, the key included (`api_key`).", "security": [ { "ApiKeyQuery": [] } ], "parameters": [ { "$ref": "#/components/parameters/format" }, { "$ref": "#/components/parameters/structure_country_iso" } ], "responses": { "200": { "$ref": "#/components/responses/StructureResult" }, "400": { "$ref": "#/components/responses/StructureBadRequest" }, "401": { "$ref": "#/components/responses/StructureAccountError" }, "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. Missing: result code 306 (HTTP 400); wrong: 301 (HTTP\n403 on the bank code and BIC endpoints, HTTP 401 on the structure endpoint).\n" } }, "parameters": { "format": { "name": "format", "in": "query", "required": true, "description": "Response format, lower case: `json` or `xml`. Missing: 306 (HTTP 400). `JSON` or `XML` in upper case:\nHTTP 200 with an **empty body** — check for an empty body before parsing.\n", "schema": { "type": "string", "enum": [ "json", "xml" ] }, "example": "json" }, "country_iso": { "name": "country_iso", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 code of the country, **upper case**: `us` is refused with 802, as is anything that is\nnot two letters; a two-letter code outside the supported list gives 803. Missing: 306.\n", "schema": { "type": "string", "pattern": "^[A-Z]{2}$" }, "example": "US" }, "nid": { "name": "nid", "in": "query", "required": true, "description": "The national bank code (NID): routing number, sort code, BLZ, clearing number, IFSC… in the exact length\nand form the country uses (the structure endpoint gives the format and an example). The value is not\ncleaned: spaces, hyphens or missing leading zeros change the length and give 804. Letters are accepted\nwhere the format has them and matched case-insensitively. Where a country has several code formats the\nlookup uses the main one. Missing: 306.\n", "schema": { "type": "string" }, "example": "322271627" }, "account": { "name": "account", "in": "query", "required": false, "description": "The domestic account number, checked against the country's account format (811 when the length is\nwrong, 812 when the format does not match) and the national check digit where the format has one\n(813; 814 for a German account). Send it in the full domestic form (the complete 23-character French\nRIB, the 20-digit Spanish CCC, the 10-digit German account with leading zeros). Not sent:\n`account_valid` is an empty string.\n", "schema": { "type": "string" }, "example": "38290008" }, "limit": { "name": "limit", "in": "query", "required": false, "description": "Number of directory records to return when the bank code has several (branches sharing a routing\nnumber). Default 1. A value that is not a positive integer, or a large one (1000 was refused, 100\naccepted), is refused with 307 (HTTP 400). Records beyond the accepted maximum cannot be paged.\n", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 5 }, "bic": { "name": "bic", "in": "query", "required": true, "description": "The BIC to look up, 8 or 11 characters, in any case. Characters other than letters and digits: 807.\nAny other length: 808. Not in the directory: result code 400. Missing: HTTP 500 with an empty body.\n", "schema": { "type": "string" }, "example": "BARCGB22XXX" }, "bic_limit": { "name": "limit", "in": "query", "required": false, "description": "Accepted, but a BIC identifies one record, so one record is returned. A value that is not a positive integer is refused with 806 (HTTP 400) in a reduced body of `success` and `error` only.", "schema": { "type": "integer", "minimum": 1 } }, "structure_country_iso": { "name": "country_iso", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 code, upper or lower case (unlike the bank code endpoint). Not two letters: 802\n(HTTP 400). Two letters without an entry: 400 *ISO Country Code not found in registry* (HTTP 400).\nMissing: HTTP 200 with an empty body.\n", "schema": { "type": "string" }, "example": "GB" } }, "responses": { "BankCodeResult": { "description": "The request was processed. `nid_valid` says whether the bank code has the right form and exists in the\ndirectory; `account_valid` whether the account passed (`\"\"` when no account was sent or the bank code\nfailed). `error` is present only when something failed: 802 country code invalid · 803 unsupported\ncountry · 804 wrong length · 805 wrong format · 801 invalid characters (listed, not observed) · 400 bank\ncode not found · 811 account length · 812 account format · 813 account check digit · 814 bank code/NID\ncheck digit (German accounts; treat like 813). For 811–814 the directory record is still returned.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankCodeResponse" }, "examples": { "us_routing": { "summary": "US routing number 322271627 — 840 branches share it, one returned (recorded 9 Oct 2026)", "value": { "query": { "country_iso": "US", "nid": "322271627", "account": "" }, "success": true, "account_valid": "", "nid_valid": true, "records_found": 840, "records_displayed": 1, "directory_results": [ { "office_type": "DB", "legal_type": "B", "institution_status": "BANK", "iso_lei_code": "7H6GLXDRUGQFU57RNE97", "bic8": "CHASUS33", "branch_bic": "XXX", "bic": "CHASUS33XXX", "chips_uid": "0002", "national_id": "322271627", "connected_bic": "CHASUS33XXX", "institution_name": "JPMORGAN CHASE BANK, NATIONAL ASSOCIATION", "branch_information": "WEST COVINA", "pob_number": "", "street_address_1": "100 S VINCENT AVE", "street_address_2": "", "street_address_3": "", "street_address_4": "", "city": "WEST COVINA", "cps": "CA", "zip_code": "91790", "country_name": "UNITED STATES OF AMERICA", "iso_country_code": "US", "subtype_indicator": "SUPE", "network_connectivity": "CCC", "service_codes": "FWRFAC" } ] } }, "account_check_failed": { "summary": "UK sort code 200415 with a wrong account check digit — record returned, code 813 (recorded 9 Oct 2026)", "value": { "query": { "country_iso": "GB", "nid": "200415", "account": "38290009" }, "success": true, "account_valid": false, "nid_valid": true, "records_found": 1, "records_displayed": 1, "directory_results": [ { "office_type": "DB", "legal_type": "B", "institution_status": "BANK", "iso_lei_code": "213800UUGANOMFJ9X769", "bic8": "BUKBGB22", "branch_bic": "XXX", "bic": "BUKBGB22XXX", "chips_uid": "", "national_id": "200415", "connected_bic": "BUKBGB22XXX", "institution_name": "BARCLAYS BANK UK PLC", "branch_information": "BARCLAYBANK B'CARD N'PTON", "pob_number": "", "street_address_1": "1 CHURCHILL PLACE", "street_address_2": "", "street_address_3": "", "street_address_4": "", "city": "LONDON", "cps": "GREATER LONDON", "zip_code": "E14 5HP", "country_name": "UNITED KINGDOM", "iso_country_code": "GB", "subtype_indicator": "SUPE", "network_connectivity": "CCC", "service_codes": "" } ], "error": { "code": "813", "message": "Invalid Account Check Digit" } } }, "not_found": { "summary": "322271628 — right length, wrong check digit, code 400 (recorded 9 Oct 2026)", "value": { "query": { "country_iso": "US", "nid": "322271628", "account": "" }, "success": true, "account_valid": "", "nid_valid": false, "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "400", "message": "BankCode(NID) not found in the official directory" } } }, "country_invalid": { "summary": "country_iso USA — code 802 (recorded 9 Oct 2026)", "value": { "query": { "country_iso": "USA", "nid": "322271627", "account": "" }, "success": true, "account_valid": "", "nid_valid": false, "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "802", "message": "Country ISO code invalid" } } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BankCodeResponse" }, "examples": { "us_routing": { "summary": "US routing number 322271627 with `format=xml` (recorded 9 Oct 2026, cut after the first fields of the record)", "description": "Booleans are `1` / `0`, empty values are empty elements, each record is a `row`, and the member\norder differs from JSON. The `error` element is always present (empty on success):\n\n```xml\n\nUS322271627118401DBBBANK7H6GLXDRUGQFU57RNE97CHASUS33XXXCHASUS33XXX…\n```\n", "value": { "query": { "country_iso": "US", "nid": "322271627", "account": "" }, "success": true, "account_valid": "", "nid_valid": true, "records_found": 840, "records_displayed": 1, "directory_results": [] } } } } } }, "BankCodeBadRequest": { "description": "A required parameter is missing (306: `api_key`, `format`, `country_iso` or `nid` — the message says *iso*) or `limit` is not a positive integer or too large (307). `query` fields empty, `success` false.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankCodeResponse" }, "examples": { "missing_nid": { "summary": "nid missing — code 306 (recorded 9 Oct 2026)", "value": { "query": { "country_iso": "", "nid": "", "account": "" }, "success": false, "account_valid": "", "nid_valid": "", "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "306", "message": "Bad Request. Required minimum parameters: api_key, format, iso, nid" } } }, "bad_limit": { "summary": "limit=0 — code 307 (recorded 9 Oct 2026)", "value": { "query": { "country_iso": "US", "nid": "021000021", "account": "" }, "success": false, "account_valid": "", "nid_valid": "", "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "307", "message": "Invalid value for 'limit' parameter" } } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BankCodeResponse" } } } }, "BankCodeAccountError": { "description": "Account error — 301 key invalid · 302 subscription expired · 303 no queries · 304 no access · 305 IP address not allowed. 301 recorded; the others follow the same path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankCodeResponse" }, "examples": { "wrong_key": { "summary": "Wrong key — code 301 (recorded 9 Oct 2026)", "value": { "query": { "country_iso": "", "nid": "", "account": "" }, "success": false, "account_valid": "", "nid_valid": "", "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "301", "message": "API Key is invalid" } } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BankCodeResponse" }, "examples": { "wrong_key": { "summary": "Wrong key with `format=xml` (recorded 9 Oct 2026)", "description": "```xml\n\n00301API Key is invalid\n```\n", "value": { "query": { "country_iso": "", "nid": "", "account": "" }, "success": false, "account_valid": "", "nid_valid": "", "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "301", "message": "API Key is invalid" } } } } } } }, "BicResult": { "description": "The request was processed. `bic_valid` true with one record; false with code 807 (invalid characters), 808 (wrong length) or 400 (not in the bank directory — also for BICs that exist in the SWIFT directory but have no bank-directory record, such as passive BICs).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BicResponse" }, "examples": { "barclays": { "summary": "BARCGB22XXX — Barclays Bank PLC; national_id is the sort code 203253 (recorded 9 Oct 2026)", "value": { "query": { "bic": "BARCGB22XXX" }, "success": true, "bic_valid": true, "records_found": 1, "records_displayed": 1, "directory_results": [ { "office_type": "HO", "legal_type": "L", "institution_status": "BANK", "iso_lei_code": "G5GSEF7VJP5I7OUK5573", "bic8": "BARCGB22", "branch_bic": "XXX", "bic": "BARCGB22XXX", "chips_uid": "007668", "national_id": "203253", "connected_bic": "BARCGB22XXX", "institution_name": "BARCLAYS BANK PLC", "branch_information": "ALL U.K. OFFICES", "pob_number": "", "street_address_1": "1 CHURCHILL PLACE", "street_address_2": "", "street_address_3": "", "street_address_4": "", "city": "LONDON", "cps": "GREATER LONDON", "zip_code": "E14 5HP", "country_name": "UNITED KINGDOM", "iso_country_code": "GB", "subtype_indicator": "SUPE", "network_connectivity": "CCC", "service_codes": "FINSCO" } ] } }, "not_found": { "summary": "ZZZZGB22 — code 400 (recorded 9 Oct 2026)", "value": { "query": { "bic": "ZZZZGB22" }, "success": true, "bic_valid": false, "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "400", "message": "BIC not found in official directory" } } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BicResponse" } } } }, "BicBadRequest": { "description": "`limit` is not a positive integer — code 806 in a reduced body of `success` and `error` only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReducedError" }, "examples": { "bad_limit": { "summary": "limit=abc (recorded 9 Oct 2026)", "value": { "success": false, "error": { "code": "806", "message": "Invalid value for 'limit' parameter" } } } } } } }, "BicAccountError": { "description": "Account error (codes 301–305); `query.bic` empty, `bic_valid` an empty string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BicResponse" }, "examples": { "wrong_key": { "summary": "Wrong key — code 301 (recorded 9 Oct 2026)", "value": { "query": { "bic": "" }, "success": false, "bic_valid": "", "records_found": "", "records_displayed": "", "directory_results": [], "error": { "code": "301", "message": "API Key is invalid" } } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/BicResponse" } } } }, "StructureResult": { "description": "The formats of the country. Lengths and length ranges are strings (Australia's account lengths are the one recorded exception, returned as numbers). Several bank-code formats may be listed; the lookup on the bank code endpoint uses the main (first) one.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructureResponse" }, "examples": { "gb": { "summary": "United Kingdom (recorded 9 Oct 2026)", "value": { "success": true, "national_id_format": [ { "COUNTRY_CODE": "GB", "COUNTRY_NAME": "UNITED KINGDOM", "NATIONAL_ID_LOCAL_NAME": "Sort Code", "NATIONAL_ID_LOCAL_ACRONYM": "SC", "CLEARING_SYSTEM": "Payments UK", "EXAMPLE": "207305", "LETTER_FORMAT": "BBRRRR", "REGEX_FORMAT": "[0-9]{2}[0-9]{4}", "ELEMENTS": "BANK_CODE,BRANCH_CODE", "LENGTH": "6", "LENGTH_IN_DB": "6" } ], "account_number_format": [ { "ISO_COUNTRY_CODE": "GB", "COUNTRY_NAME": "UNITED KINGDOM", "ACCOUNT_NB_TYPE": "Account number - Standard", "ACCOUNT_NB_LOCAL_NAME": "Account number", "EXAMPLE": "31219065", "LETTER_FORMAT": "AAAAAAAA", "REGEX_FORMAT": "[0-9]{8}", "ELEMENTS": "ACCOUNT", "MIN_LENGTH": "8", "MAX_LENGTH": "8" } ] } }, "us": { "summary": "United States — three bank-code formats (recorded 9 Oct 2026)", "value": { "success": true, "national_id_format": [ { "COUNTRY_CODE": "US", "COUNTRY_NAME": "UNITED STATES OF AMERICA", "NATIONAL_ID_LOCAL_NAME": "Routing Number", "NATIONAL_ID_LOCAL_ACRONYM": "ABA", "CLEARING_SYSTEM": "American Bankers Association (ABA)", "EXAMPLE": "211770093", "LETTER_FORMAT": "BBBBIIIIK", "REGEX_FORMAT": "[0-9]{4}[0-9]{4}[0-9]{1}", "ELEMENTS": "BANK_CODE,INSTITUTION_CODE,CHECKSUM", "LENGTH": "9", "LENGTH_IN_DB": "9" }, { "COUNTRY_CODE": "US", "COUNTRY_NAME": "UNITED STATES OF AMERICA", "NATIONAL_ID_LOCAL_NAME": "CHIPS ID", "NATIONAL_ID_LOCAL_ACRONYM": "CHIPSID", "CLEARING_SYSTEM": "The Clearing House Payments Company L.L.C", "EXAMPLE": "0049", "LETTER_FORMAT": "BBBB", "REGEX_FORMAT": "[0-9]{4}", "ELEMENTS": "BANK_CODE", "LENGTH": "4", "LENGTH_IN_DB": "4" }, { "COUNTRY_CODE": "US", "COUNTRY_NAME": "UNITED STATES OF AMERICA", "NATIONAL_ID_LOCAL_NAME": "CHIPS Universal ID", "NATIONAL_ID_LOCAL_ACRONYM": "CHIPSUID", "CLEARING_SYSTEM": "The Clearing House Payments Company L.L.C", "EXAMPLE": "004966", "LETTER_FORMAT": "BBBBBB", "REGEX_FORMAT": "[0-9]{6}", "ELEMENTS": "BANK_CODE", "LENGTH": "6", "LENGTH_IN_DB": "6" } ], "account_number_format": [ { "ISO_COUNTRY_CODE": "US", "COUNTRY_NAME": "UNITED STATES OF AMERICA", "ACCOUNT_NB_TYPE": "Account number - Standard", "ACCOUNT_NB_LOCAL_NAME": "Account number", "EXAMPLE": "30806988100215886453015978854133029", "LETTER_FORMAT": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "REGEX_FORMAT": "[A-Z0-9]{1,35}", "ELEMENTS": "ACCOUNT", "MIN_LENGTH": "1", "MAX_LENGTH": "35" } ] } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/StructureResponse" } } } }, "StructureBadRequest": { "description": "802 country code not two letters · 400 no entry for this country code · 306 `api_key` or `format` missing. Both lists empty, `success` false. (A missing `country_iso` is a 200 with an empty body.)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructureResponse" }, "examples": { "unknown": { "summary": "XX — code 400 (recorded 9 Oct 2026)", "value": { "success": false, "national_id_format": [], "account_number_format": [], "error": { "code": "400", "message": "ISO Country Code not found in registry" } } }, "invalid": { "summary": "USA — code 802 (recorded 9 Oct 2026)", "value": { "success": false, "national_id_format": [], "account_number_format": [], "error": { "code": "802", "message": "Country ISO code invalid" } } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/StructureResponse" } } } }, "StructureAccountError": { "description": "Account error on the structure endpoint — HTTP 401 (not 403), codes 301–305.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StructureResponse" }, "examples": { "wrong_key": { "summary": "Wrong key — code 301 (recorded 9 Oct 2026)", "value": { "success": false, "national_id_format": [], "account_number_format": [], "error": { "code": "301", "message": "API Key is invalid" } } } } }, "application/xml": { "schema": { "$ref": "#/components/schemas/StructureResponse" } } } }, "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 body. Recorded for a parameter sent in a form the API cannot read (`nid[]`) and for a missing `bic` on the BIC endpoint; for anything else a temporary problem — retry with increasing delays.", "content": { "text/html": { "schema": { "type": "string" } } } } }, "schemas": { "BankCodeRequest": { "type": "object", "required": [ "api_key", "format", "country_iso", "nid" ], "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; upper case gives a 200 with an empty body." }, "country_iso": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2, upper case.", "examples": [ "US", "GB", "DE" ] }, "nid": { "type": "string", "description": "The national bank code in the exact form the country uses (not cleaned).", "examples": [ "322271627", "200415", "37040044", "SBIN0000001" ] }, "account": { "type": "string", "description": "Domestic account number in its full form, optional.", "examples": [ "38290008", "0532013000" ] }, "limit": { "type": "integer", "minimum": 1, "default": 1, "description": "Directory records to return when the bank code has several.", "examples": [ 5 ] } } }, "BicRequest": { "type": "object", "required": [ "api_key", "format", "bic" ], "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" ] }, "bic": { "type": "string", "description": "The BIC, 8 or 11 characters, any case.", "examples": [ "BARCGB22XXX", "DEUTDEFF" ] }, "limit": { "type": "integer", "minimum": 1, "description": "Accepted; one record is returned for a BIC anyway." } } }, "StructureRequest": { "type": "object", "required": [ "api_key", "format", "country_iso" ], "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" ] }, "country_iso": { "type": "string", "description": "ISO 3166-1 alpha-2, upper or lower case.", "examples": [ "GB", "us" ] } } }, "BoolOrEmpty": { "description": "`true` / `false`, or an empty string when the value does not apply (in XML `1`, `0` or an empty element).", "type": [ "boolean", "string" ], "enum": [ true, false, "" ] }, "IntOrEmpty": { "description": "A number, or an empty string when the lookup failed.", "type": [ "integer", "string" ] }, "ResultError": { "type": "object", "required": [ "code", "message" ], "description": "Present in JSON only when something failed; in XML always present, empty on success.", "properties": { "code": { "type": "string", "pattern": "^[0-9]{3}$", "description": "Three-digit string. 3xx account/request · 400 not found · 8xx input." }, "message": { "type": "string" } }, "additionalProperties": false }, "BankCodeResponse": { "type": "object", "required": [ "query", "success", "account_valid", "nid_valid", "records_found", "records_displayed", "directory_results" ], "properties": { "query": { "type": "object", "required": [ "country_iso", "nid", "account" ], "description": "`country_iso`, `nid` and `account` exactly as received (no case conversion); `account` is an empty string when not sent. All three empty in the answer to a request or account error.", "properties": { "country_iso": { "type": "string" }, "nid": { "type": "string" }, "account": { "type": "string" } } }, "success": { "type": "boolean", "description": "`true` when processed, including when the bank code or account failed validation; `false` for request errors (306, 307) and account errors (301–305)." }, "account_valid": { "$ref": "#/components/schemas/BoolOrEmpty", "description": "`true` when the account passed the format check and, where the country has one, the check digit; `false` with 811–814; `\"\"` when no account was sent or the bank code failed." }, "nid_valid": { "$ref": "#/components/schemas/BoolOrEmpty", "description": "`true` when the bank code has the right form and exists in the directory; `false` with 801–805 or 400; `\"\"` in the answer to a request error." }, "records_found": { "$ref": "#/components/schemas/IntOrEmpty", "description": "Number of directory records with this bank code (840 for 322271627); `\"\"` when the bank code failed." }, "records_displayed": { "$ref": "#/components/schemas/IntOrEmpty", "description": "Number of records in `directory_results` — 1 by default, up to `limit`; `\"\"` when the bank code failed." }, "directory_results": { "type": "array", "description": "The records (25 fields each); empty when the bank code failed.", "items": { "$ref": "#/components/schemas/DirectoryRecord" }, "xml": { "wrapped": true } }, "error": { "$ref": "#/components/schemas/ResultError" } }, "xml": { "name": "result" } }, "BicResponse": { "type": "object", "required": [ "query", "success", "bic_valid", "records_found", "records_displayed", "directory_results" ], "properties": { "query": { "type": "object", "required": [ "bic" ], "properties": { "bic": { "type": "string", "description": "The BIC as received; empty on an account error." } } }, "success": { "type": "boolean" }, "bic_valid": { "$ref": "#/components/schemas/BoolOrEmpty", "description": "`true` when the BIC has the right form and exists in the directory; `false` with 807, 808 or 400; `\"\"` on an account error." }, "records_found": { "$ref": "#/components/schemas/IntOrEmpty", "description": "1 for a BIC that was found; `\"\"` otherwise." }, "records_displayed": { "$ref": "#/components/schemas/IntOrEmpty" }, "directory_results": { "type": "array", "maxItems": 1, "description": "One record; `national_id` carries the bank code the BIC corresponds to (empty when the BIC has none).", "items": { "$ref": "#/components/schemas/DirectoryRecord" }, "xml": { "wrapped": true } }, "error": { "$ref": "#/components/schemas/ResultError" } }, "xml": { "name": "result" } }, "ReducedError": { "type": "object", "required": [ "success", "error" ], "additionalProperties": false, "properties": { "success": { "type": "boolean" }, "error": { "$ref": "#/components/schemas/ResultError" } } }, "StructureResponse": { "type": "object", "required": [ "success", "national_id_format", "account_number_format" ], "properties": { "success": { "type": "boolean" }, "national_id_format": { "type": "array", "items": { "$ref": "#/components/schemas/NationalIdFormat" } }, "account_number_format": { "type": "array", "items": { "$ref": "#/components/schemas/AccountNumberFormat" } }, "error": { "$ref": "#/components/schemas/ResultError" } }, "xml": { "name": "result" } }, "NationalIdFormat": { "type": "object", "required": [ "COUNTRY_CODE", "COUNTRY_NAME", "NATIONAL_ID_LOCAL_NAME", "NATIONAL_ID_LOCAL_ACRONYM", "CLEARING_SYSTEM", "EXAMPLE", "LETTER_FORMAT", "REGEX_FORMAT", "ELEMENTS", "LENGTH", "LENGTH_IN_DB" ], "properties": { "COUNTRY_CODE": { "type": "string" }, "COUNTRY_NAME": { "type": "string" }, "NATIONAL_ID_LOCAL_NAME": { "type": "string", "description": "What the code is called locally (*Routing Number*, *Sort Code*, *Bankleitzahl*)." }, "NATIONAL_ID_LOCAL_ACRONYM": { "type": "string", "description": "May be empty." }, "CLEARING_SYSTEM": { "type": "string", "description": "The clearing system or body that issues the code." }, "EXAMPLE": { "type": "string", "description": "A valid example in the right length." }, "LETTER_FORMAT": { "type": "string", "description": "One letter per position: B bank code, R branch code, I institution code, K check digit, L location code, O other, N transit number, A area code, U unit code, E emirate code." }, "REGEX_FORMAT": { "type": "string", "description": "Regular expression the code must match; anchor it yourself." }, "ELEMENTS": { "type": "string", "description": "The elements in order, comma-separated." }, "LENGTH": { "type": "string", "description": "Length of the code as sent (a string)." }, "LENGTH_IN_DB": { "type": "string", "description": "Length as stored (a string)." } } }, "AccountNumberFormat": { "type": "object", "required": [ "ISO_COUNTRY_CODE", "COUNTRY_NAME", "ACCOUNT_NB_TYPE", "ACCOUNT_NB_LOCAL_NAME", "EXAMPLE", "LETTER_FORMAT", "REGEX_FORMAT", "ELEMENTS", "MIN_LENGTH", "MAX_LENGTH" ], "properties": { "ISO_COUNTRY_CODE": { "type": "string" }, "COUNTRY_NAME": { "type": "string" }, "ACCOUNT_NB_TYPE": { "type": "string" }, "ACCOUNT_NB_LOCAL_NAME": { "type": "string" }, "EXAMPLE": { "type": "string" }, "LETTER_FORMAT": { "type": "string", "description": "One letter per position, same letters as the bank code plus A account." }, "REGEX_FORMAT": { "type": "string" }, "ELEMENTS": { "type": "string", "description": "Elements in order, comma-separated; `CHECKSUM` marks a check digit in the number." }, "MIN_LENGTH": { "type": [ "string", "integer" ], "description": "Accepted length range, as strings (`\"8\"`); Australia alone returns numbers (`5`, `11`) — read the value as a number either way." }, "MAX_LENGTH": { "type": [ "string", "integer" ] } } }, "DirectoryRecord": { "type": "object", "required": [ "office_type", "legal_type", "institution_status", "iso_lei_code", "bic8", "branch_bic", "bic", "chips_uid", "national_id", "connected_bic", "institution_name", "branch_information", "pob_number", "street_address_1", "street_address_2", "street_address_3", "street_address_4", "city", "cps", "zip_code", "country_name", "iso_country_code", "subtype_indicator", "network_connectivity", "service_codes" ], "description": "A bank-directory record, 25 fields, text upper case as registered. Empty strings where the directory has no value.", "properties": { "office_type": { "type": "string", "description": "HO head office · DB domestic branch or department · SB sub-domestic branch · FB foreign branch · SF sub-foreign branch · UC unclassified." }, "legal_type": { "type": "string", "description": "L legal entity · B business entity (branch or department) · U unknown." }, "institution_status": { "type": "string", "description": "Type of institution, four letters (BANK, COOP, CBMA, ASSM, CORP, CRUN, ICSD, INVM, MONX, NPAA, PYMI, SLBH, SUFI, XCHG, OTHR)." }, "iso_lei_code": { "type": "string", "description": "Legal Entity Identifier (ISO 17442, 20 characters); empty when none." }, "bic8": { "type": "string", "description": "First eight characters of the BIC." }, "branch_bic": { "type": "string", "description": "Branch code of the BIC; `XXX` for the head office." }, "bic": { "type": "string", "description": "The 11-character BIC of the record." }, "chips_uid": { "type": "string", "description": "CHIPS Universal Identifier, up to 6 digits with leading zeros; empty when none." }, "national_id": { "type": "string", "description": "The bank code of the record as stored in the directory; empty for a BIC without a national code." }, "connected_bic": { "type": "string", "description": "The BIC through which the record is reached on the SWIFT network." }, "institution_name": { "type": "string" }, "branch_information": { "type": "string", "description": "Branch or department name; often empty." }, "pob_number": { "type": "string", "description": "P.O. box number and postal code, comma-separated; empty when none." }, "street_address_1": { "type": "string" }, "street_address_2": { "type": "string" }, "street_address_3": { "type": "string" }, "street_address_4": { "type": "string" }, "city": { "type": "string" }, "cps": { "type": "string", "description": "County, province or state." }, "zip_code": { "type": "string" }, "country_name": { "type": "string" }, "iso_country_code": { "type": "string" }, "subtype_indicator": { "type": "string", "description": "Business type of the entity, four letters (SUPE SWIFT member or sub-member, NSWB non-connected BIC, TRCO treasury counterparty…)." }, "network_connectivity": { "type": "string", "description": "Three letters for FIN, InterAct and FileAct: C connected, N not connected (CCC fully connected, CNN FIN only, NNN not connected)." }, "service_codes": { "type": "string", "description": "SWIFT service and market-infrastructure codes concatenated without separators in alphabetical order (`EBAERPFINSCOTGT` = EBA, ERP, FIN, SCO, TGT): split every three characters. Empty when none." } }, "xml": { "name": "row" } } } } }