Bank Suite API

Part of the Bank Suite service: bank code and account number validation for countries that do not use the IBAN, backed by a bank directory of 195 countries that is updated monthly. One request validates a domestic bank code (routing number, sort code, BLZ, IFSC…) and returns the institution and branch behind it with BIC, LEI, address and SWIFT connectivity; an account number can be checked in the same call against the country’s format and check digit. Two more endpoints find the bank code that belongs to a BIC and describe the bank code and account formats of each country.

Endpoints

Validate a bank code, optionally with an account number:

Find the bank code and record behind a BIC:

Bank code and account number formats of a country:

• 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 bank code or account is valid or not; the outcome is in the body. 400 for a request error (306, 307) and for the structure endpoint’s country errors (802, 400). 403 for an account error (301–305) on the bank code and BIC endpoints, 401 for the same on the structure endpoint. 429 when the rate limit is exceeded (HTML page). 500 with an empty body for a malformed parameter and for a missing bic.
• Error responses keep the normal structure (JSON and XML); only the bank code endpoint’s request errors and the structure endpoint answer with HTTP 400. Two exceptions return HTTP 200 with an empty body: format in upper case, and the structure endpoint without country_iso.
• Responses are UTF-8; Content-Type is application/json or application/xml. Directory text is upper case as registered.
• Typical response time is about 0.1 s for all three endpoints; 0.2 s for 100 records.
• Submitted bank codes and 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/banksuite/nid/" -d api_key=YOUR_API_KEY -d format=json -d country_iso=US -d nid=322271627

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

All three endpoints take the key and the format; each has its own input. Parameters an endpoint does not know are ignored, and iso is not an alias of country_iso.

Bank code endpoint

BIC endpoint

Structure endpoint

Example request

Every example validates the same bank code: US routing number 322271627 (JPMorgan Chase, the example from the previous documentation); its response is shown in the next section. Replace YOUR_API_KEY with the key from API Access.

curl "https://api.iban.com/clients/api/banksuite/nid/" \
  -d api_key=YOUR_API_KEY \
  -d format=json \
  -d country_iso=US \
  -d nid=322271627

<?php
$ch = curl_init('https://api.iban.com/clients/api/banksuite/nid/');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'api_key'     => 'YOUR_API_KEY',
        'format'      => 'json',
        'country_iso' => 'US',
        'nid'         => '322271627',
    ]),
]);
$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/banksuite/nid/', data={
    'api_key': 'YOUR_API_KEY',
    'format': 'json',
    'country_iso': 'US',
    'nid': '322271627',
})
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_iso: 'US',
  nid: '322271627',
});

fetch('https://api.iban.com/clients/api/banksuite/nid/', { 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 BankSuiteApi {
    public static void main(String[] args) throws Exception {
        String body = "api_key=YOUR_API_KEY&format=json&country_iso=US&nid=322271627";
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.iban.com/clients/api/banksuite/nid/"))
            .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_iso"] = "US",
    ["nid"]         = "322271627",
});
var response = await client.PostAsync("https://api.iban.com/clients/api/banksuite/nid/", 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_iso": {"US"},
		"nid":         {"322271627"},
	}
	resp, err := http.PostForm("https://api.iban.com/clients/api/banksuite/nid/", 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 other two endpoints take the same form:

curl "https://api.iban.com/clients/api/banksuite/bic/" \
  -d api_key=YOUR_API_KEY \
  -d format=json \
  -d bic=BARCGB22XXX

curl "https://api.iban.com/clients/api/banksuite/structure/" \
  -d api_key=YOUR_API_KEY \
  -d format=json \
  -d country_iso=GB

Response

A bank code response has query, success, account_valid, nid_valid, records_found, records_displayed, directory_results and, when something failed, error. JSON and XML list them in a different order (XML puts the two counts, records_displayed then records_found, before the two flags), so address them by name. The response to the example request:

{
   "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"
      }
   ]
}

<?xml version="1.0"?>
<result>
   <query>
      <country_iso>US</country_iso>
      <nid>322271627</nid>
      <account/>
   </query>
   <success>1</success>
   <records_displayed>1</records_displayed>
   <records_found>840</records_found>
   <account_valid/>
   <nid_valid>1</nid_valid>
   <directory_results>
      <row>
         <office_type>DB</office_type>
         <legal_type>B</legal_type>
         <institution_status>BANK</institution_status>
         <iso_lei_code>7H6GLXDRUGQFU57RNE97</iso_lei_code>
         <bic8>CHASUS33</bic8>
         <branch_bic>XXX</branch_bic>
         <bic>CHASUS33XXX</bic>
         <chips_uid>0002</chips_uid>
         <national_id>322271627</national_id>
         <connected_bic>CHASUS33XXX</connected_bic>
         <institution_name>JPMORGAN CHASE BANK, NATIONAL ASSOCIATION</institution_name>
         <branch_information>WEST COVINA</branch_information>
         <pob_number/>
         <street_address_1>100 S VINCENT AVE</street_address_1>
         <street_address_2/>
         <street_address_3/>
         <street_address_4/>
         <city>WEST COVINA</city>
         <cps>CA</cps>
         <zip_code>91790</zip_code>
         <country_name>UNITED STATES OF AMERICA</country_name>
         <iso_country_code>US</iso_country_code>
         <subtype_indicator>SUPE</subtype_indicator>
         <network_connectivity>CCC</network_connectivity>
         <service_codes>FWRFAC</service_codes>
      </row>
   </directory_results>
   <error>
      <code/>
      <message/>
   </error>
</result>

directory_results

One object per record, 25 fields, all strings; a field without a value is an empty string (an empty element in XML). The values of the coded fields are listed under Field values.

Bank code with a valid account

UK sort code 200415 with account 38290008 (the Barclays test pair that passes the modulus check). No error member:

{
   "query": {
      "country_iso": "GB",
      "nid": "200415",
      "account": "38290008"
   },
   "success": true,
   "account_valid": true,
   "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": ""
      }
   ]
}

Bank code with an invalid account

The same sort code with the last digit of the account changed: the bank is still returned, account_valid is false and error explains why:

{
   "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"
   }
}

Bank code not found

Routing number 322271628 (wrong check digit). Note the empty strings in the count fields:

{
   "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"
   }
}

Request error

HTTP 400, nid missing; 307 has the same shape:

{
   "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"
   }
}

Account error

HTTP 403, result code 301 shown; 302 to 305 have the same shape with the messages from the code table. In XML success and nid_valid are 0:

{
   "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"
   }
}

<?xml version="1.0"?>
<result>
   <query>
      <country_iso/>
      <nid/>
      <account/>
   </query>
   <success>0</success>
   <records_displayed/>
   <records_found/>
   <account_valid/>
   <nid_valid>0</nid_valid>
   <directory_results/>
   <error>
      <code>301</code>
      <message>API Key is invalid</message>
   </error>
</result>

BIC lookup

The BIC endpoint answers the reverse question: which bank code and record belong to a BIC. The response has query.bic, success, bic_valid, records_found, records_displayed, directory_results with one record, and error on failure. BARCGB22XXX resolves to sort code 203253:

{
   "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"
      }
   ]
}

<?xml version="1.0"?>
<result>
   <query>
      <bic>BARCGB22XXX</bic>
   </query>
   <success>1</success>
   <records_displayed>1</records_displayed>
   <records_found>1</records_found>
   <directory_results>
      <row>
         <office_type>HO</office_type>
         <legal_type>L</legal_type>
         <institution_status>BANK</institution_status>
         <iso_lei_code>G5GSEF7VJP5I7OUK5573</iso_lei_code>
         <bic8>BARCGB22</bic8>
         <branch_bic>XXX</branch_bic>
         <bic>BARCGB22XXX</bic>
         <chips_uid>007668</chips_uid>
         <national_id>203253</national_id>
         <connected_bic>BARCGB22XXX</connected_bic>
         <institution_name>BARCLAYS BANK PLC</institution_name>
         <branch_information>ALL U.K. OFFICES</branch_information>
         <pob_number/>
         <street_address_1>1 CHURCHILL PLACE</street_address_1>
         <street_address_2/>
         <street_address_3/>
         <street_address_4/>
         <city>LONDON</city>
         <cps>GREATER LONDON</cps>
         <zip_code>E14 5HP</zip_code>
         <country_name>UNITED KINGDOM</country_name>
         <iso_country_code>GB</iso_country_code>
         <subtype_indicator>SUPE</subtype_indicator>
         <network_connectivity>CCC</network_connectivity>
         <service_codes>FINSCO</service_codes>
      </row>
   </directory_results>
   <error>
      <code/>
      <message/>
   </error>
</result>

BIC not found

{
   "query": {
      "bic": "ZZZZGB22"
   },
   "success": true,
   "bic_valid": false,
   "records_found": "",
   "records_displayed": "",
   "directory_results": [],
   "error": {
      "code": "400",
      "message": "BIC not found in official directory"
   }
}

<?xml version="1.0"?>
<result>
   <query>
      <bic>ZZZZGB22</bic>
   </query>
   <success>1</success>
   <records_displayed/>
   <records_found/>
   <directory_results/>
   <error>
      <code>400</code>
      <message>BIC not found in official directory</message>
   </error>
</result>

This endpoint searches the bank directory, not the SWIFT BIC directory: a BIC that exists but has no bank-directory record (a passive participant such as UNCRITM1, or a branch BIC the directory does not carry) is answered with 400. To validate a BIC as such, use the BIC Validation API.

Country formats

The structure endpoint describes what a country’s bank code and account number look like, so that you can validate the input before calling the bank code endpoint and build the right account value. A country can have several bank code formats (the United States has the routing number, the CHIPS ID and the CHIPS UID; Spain an 8- and a 9-digit form) and several account formats (Sweden three), so both members are arrays. The United Kingdom:

{
   "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"
      }
   ]
}

national_id_format

account_number_format

Examples and IBAN-style accounts

The EXAMPLE values are illustrative, not guaranteed to be in the directory: of the 274 bank code examples returned for all countries, 200 are found by the bank code endpoint and 74 are not (territories reuse the example of their parent country, and some are outdated). For 22 countries, mostly in West and Central Africa, the domestic account number is the IBAN itself and the account format starts with COUNTRY_CODE,CHECKSUM; send the IBAN as account there. 28 countries have no account format, so account cannot be validated for them.

Several formats, and the XML form

In XML the formats of a country are written one after another inside national_id_format and account_number_format without a wrapping element: a new format starts at every COUNTRY_CODE / ISO_COUNTRY_CODE. Use JSON when a country can have several formats. The United States in XML, three bank code formats:

<?xml version="1.0"?>
<result>
   <success>true</success>
   <national_id_format>
      <COUNTRY_CODE>US</COUNTRY_CODE>
      <COUNTRY_NAME>UNITED STATES OF AMERICA</COUNTRY_NAME>
      <NATIONAL_ID_LOCAL_NAME>Routing Number</NATIONAL_ID_LOCAL_NAME>
      <NATIONAL_ID_LOCAL_ACRONYM>ABA</NATIONAL_ID_LOCAL_ACRONYM>
      <CLEARING_SYSTEM>American Bankers Association (ABA)</CLEARING_SYSTEM>
      <EXAMPLE>211770093</EXAMPLE>
      <LETTER_FORMAT>BBBBIIIIK</LETTER_FORMAT>
      <REGEX_FORMAT>[0-9]{4}[0-9]{4}[0-9]{1}</REGEX_FORMAT>
      <ELEMENTS>BANK_CODE,INSTITUTION_CODE,CHECKSUM</ELEMENTS>
      <LENGTH>9</LENGTH>
      <LENGTH_IN_DB>9</LENGTH_IN_DB>
      <COUNTRY_CODE>US</COUNTRY_CODE>
      <COUNTRY_NAME>UNITED STATES OF AMERICA</COUNTRY_NAME>
      <NATIONAL_ID_LOCAL_NAME>CHIPS ID</NATIONAL_ID_LOCAL_NAME>
      <NATIONAL_ID_LOCAL_ACRONYM>CHIPSID</NATIONAL_ID_LOCAL_ACRONYM>
      <CLEARING_SYSTEM>The Clearing House Payments Company L.L.C</CLEARING_SYSTEM>
      <EXAMPLE>0049</EXAMPLE>
      <LETTER_FORMAT>BBBB</LETTER_FORMAT>
      <REGEX_FORMAT>[0-9]{4}</REGEX_FORMAT>
      <ELEMENTS>BANK_CODE</ELEMENTS>
      <LENGTH>4</LENGTH>
      <LENGTH_IN_DB>4</LENGTH_IN_DB>
      <COUNTRY_CODE>US</COUNTRY_CODE>
      <COUNTRY_NAME>UNITED STATES OF AMERICA</COUNTRY_NAME>
      <NATIONAL_ID_LOCAL_NAME>CHIPS Universal ID</NATIONAL_ID_LOCAL_NAME>
      <NATIONAL_ID_LOCAL_ACRONYM>CHIPSUID</NATIONAL_ID_LOCAL_ACRONYM>
      <CLEARING_SYSTEM>The Clearing House Payments Company L.L.C</CLEARING_SYSTEM>
      <EXAMPLE>004966</EXAMPLE>
      <LETTER_FORMAT>BBBBBB</LETTER_FORMAT>
      <REGEX_FORMAT>[0-9]{6}</REGEX_FORMAT>
      <ELEMENTS>BANK_CODE</ELEMENTS>
      <LENGTH>6</LENGTH>
      <LENGTH_IN_DB>6</LENGTH_IN_DB>
   </national_id_format>
   <account_number_format>
      <ISO_COUNTRY_CODE>US</ISO_COUNTRY_CODE>
      <COUNTRY_NAME>UNITED STATES OF AMERICA</COUNTRY_NAME>
      <ACCOUNT_NB_TYPE>Account number - Standard</ACCOUNT_NB_TYPE>
      <ACCOUNT_NB_LOCAL_NAME>Account number</ACCOUNT_NB_LOCAL_NAME>
      <EXAMPLE>30806988100215886453015978854133029</EXAMPLE>
      <LETTER_FORMAT>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</LETTER_FORMAT>
      <REGEX_FORMAT>[A-Z0-9]{1,35}</REGEX_FORMAT>
      <ELEMENTS>ACCOUNT</ELEMENTS>
      <MIN_LENGTH>1</MIN_LENGTH>
      <MAX_LENGTH>35</MAX_LENGTH>
   </account_number_format>
   <error>
      <code/>
      <message/>
   </error>
</result>

Unknown country

HTTP 400 with the structure of a normal response and empty arrays; 802 has the same shape:

{
   "success": false,
   "national_id_format": [],
   "account_number_format": [],
   "error": {
      "code": "400",
      "message": "ISO Country Code not found in registry"
   }
}

Result codes

A result code is a three-digit string in error.code. On the bank code and BIC endpoints, 8xx codes and 400 come with HTTP 200 and describe the input; 306 and 307 come with HTTP 400; 3xx account errors with HTTP 403. The structure endpoint answers every error with HTTP 400 (401 for account errors).

Bank code endpoint

BIC endpoint

Structure endpoint

Request errors

Account errors

Handling errors

What each outcome means for your code. Lookups are deterministic for a given input; the directory is refreshed monthly, so if you cache responses, give the cache a limited lifetime.

Reading the result

• A bank code is valid when nid_valid is true: it has the right form and is in the directory. The first record in directory_results is the bank; when records_found is above 1 the code is shared by several branches and limit lists them.
• An account is valid when account_valid is true. What that proves depends on the country: the number matches the format (characters and length from the structure endpoint) and, where the format has a CHECKSUM element, the check digit is right. Where there is no check digit (United States, Netherlands, Australia…) a wrong but well-formed number is still reported valid. Verified in testing with a valid number and an altered copy: the check digit is caught for BA, BE, DE, EE, FR, GB, HR, IT, MC, ME, MK, PT, RS, SI, XK (account_valid is computed even when the bank code itself is not in the directory). In Germany the check depends on the bank’s published method; a bank without one accepts any well-formed number. Under review: for CZ, ES, HU and TN valid numbers (the IBAN registry examples) are answered 813/814, for MX an altered CLABE is accepted, and for MA, NO, SE, SK and TL the directory’s own example accounts are rejected; do not rely on account_valid for these ten countries until this note is gone. Everywhere else the format check applies only (AT, CH, IS, IL, LI, NL, PL, US…), including 28 countries whose account format lists a check digit that is not verified (AR, DK, VE…).
• Decide on nid_valid, account_valid and error.code, never on HTTP status alone, and never on the presence of error in XML (it is always there).
• records_found, records_displayed and account_valid change type: numbers and booleans on success, empty strings on failure. Test nid_valid first.
• Send the bank code exactly as the structure endpoint describes it: full length with leading zeros, no separators. Clean the user’s input yourself; the API does not.
• Use connected_bic for routing a SWIFT payment and bic for identification; they differ when the record’s own BIC is not connected (network_connectivity NNN).
• Names, addresses and identifiers come from the directory as registered and change with each monthly release; the example records on this page were recorded on 9 October 2026.

Supported countries

195 countries, recorded from the structure endpoint on 9 October 2026: the local name of the bank code, its length (several lengths where the country has more than one form; 59 countries have more than one form, 57 of them with different lengths), and what account_valid proves there: yes – the check digit is verified (tested with a valid number and an altered copy); format only – characters and length are checked, a wrong but well-formed number passes; under review – see Reading the result; no account format – the directory has no account format for the country. Egypt and Iraq answer the structure endpoint although they are not on the service’s published list (Cuba has an account format but no bank code format and is left out).

Field values

institution_status

subtype_indicator

service_codes

The three-character codes that can appear concatenated in service_codes: SWIFT services and EU-wide infrastructures first, then national market infrastructures by country.

XML schemas

One schema per endpoint, matching the responses as the API sends them: every leaf is a string that may be empty, directory_results holds zero or more row elements, and the structure endpoint’s formats repeat without a wrapper.

banksuite-nid.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <!-- Bank Suite API, /banksuite/nid/ response. Every leaf is a string and may be empty: codes keep their leading zeros,
       flags are 1/0, counts are empty on an error. -->
  <xs:complexType name="record">
    <xs:sequence>
      <xs:element name="office_type" type="xs:string"/>
      <xs:element name="legal_type" type="xs:string"/>
      <xs:element name="institution_status" type="xs:string"/>
      <xs:element name="iso_lei_code" type="xs:string"/>
      <xs:element name="bic8" type="xs:string"/>
      <xs:element name="branch_bic" type="xs:string"/>
      <xs:element name="bic" type="xs:string"/>
      <xs:element name="chips_uid" type="xs:string"/>
      <xs:element name="national_id" type="xs:string"/>
      <xs:element name="connected_bic" type="xs:string"/>
      <xs:element name="institution_name" type="xs:string"/>
      <xs:element name="branch_information" type="xs:string"/>
      <xs:element name="pob_number" type="xs:string"/>
      <xs:element name="street_address_1" type="xs:string"/>
      <xs:element name="street_address_2" type="xs:string"/>
      <xs:element name="street_address_3" type="xs:string"/>
      <xs:element name="street_address_4" type="xs:string"/>
      <xs:element name="city" type="xs:string"/>
      <xs:element name="cps" type="xs:string"/>
      <xs:element name="zip_code" type="xs:string"/>
      <xs:element name="country_name" type="xs:string"/>
      <xs:element name="iso_country_code" type="xs:string"/>
      <xs:element name="subtype_indicator" type="xs:string"/>
      <xs:element name="network_connectivity" type="xs:string"/>
      <xs:element name="service_codes" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="error">
    <xs:sequence>
      <xs:element name="code" type="xs:string"/>
      <xs:element name="message" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
  <xs:element name="result">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="query">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="country_iso" type="xs:string"/>
              <xs:element name="nid" type="xs:string"/>
              <xs:element name="account" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="success" type="xs:string"/>
        <xs:element name="records_displayed" type="xs:string"/>
        <xs:element name="records_found" type="xs:string"/>
        <xs:element name="account_valid" type="xs:string"/>
        <xs:element name="nid_valid" type="xs:string"/>
        <xs:element name="directory_results">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="row" type="record" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="error" type="error"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

banksuite-bic.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <!-- Bank Suite API, /banksuite/bic/ response. Every leaf is a string and may be empty. -->
  <xs:complexType name="record">
    <xs:sequence>
      <xs:element name="office_type" type="xs:string"/>
      <xs:element name="legal_type" type="xs:string"/>
      <xs:element name="institution_status" type="xs:string"/>
      <xs:element name="iso_lei_code" type="xs:string"/>
      <xs:element name="bic8" type="xs:string"/>
      <xs:element name="branch_bic" type="xs:string"/>
      <xs:element name="bic" type="xs:string"/>
      <xs:element name="chips_uid" type="xs:string"/>
      <xs:element name="national_id" type="xs:string"/>
      <xs:element name="connected_bic" type="xs:string"/>
      <xs:element name="institution_name" type="xs:string"/>
      <xs:element name="branch_information" type="xs:string"/>
      <xs:element name="pob_number" type="xs:string"/>
      <xs:element name="street_address_1" type="xs:string"/>
      <xs:element name="street_address_2" type="xs:string"/>
      <xs:element name="street_address_3" type="xs:string"/>
      <xs:element name="street_address_4" type="xs:string"/>
      <xs:element name="city" type="xs:string"/>
      <xs:element name="cps" type="xs:string"/>
      <xs:element name="zip_code" type="xs:string"/>
      <xs:element name="country_name" type="xs:string"/>
      <xs:element name="iso_country_code" type="xs:string"/>
      <xs:element name="subtype_indicator" type="xs:string"/>
      <xs:element name="network_connectivity" type="xs:string"/>
      <xs:element name="service_codes" type="xs:string"/>
    </xs:sequence>
  </xs:complexType>
  <xs:element name="result">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="query">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="bic" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="success" type="xs:string"/>
        <xs:element name="records_displayed" type="xs:string"/>
        <xs:element name="records_found" type="xs:string"/>
        <xs:element name="directory_results">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="row" type="record" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="error">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="code" type="xs:string"/>
              <xs:element name="message" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

banksuite-structure.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <!-- Bank Suite API, /banksuite/structure/ response. A country can have several bank code formats and several account
       formats; in XML they follow each other inside one element without a wrapper, so the group of elements repeats
       (a new format starts at every COUNTRY_CODE / ISO_COUNTRY_CODE). -->
  <xs:element name="result">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="success" type="xs:string"/>
        <xs:element name="national_id_format">
          <xs:complexType>
            <xs:sequence minOccurs="0" maxOccurs="unbounded">
              <xs:element name="COUNTRY_CODE" type="xs:string"/>
              <xs:element name="COUNTRY_NAME" type="xs:string"/>
              <xs:element name="NATIONAL_ID_LOCAL_NAME" type="xs:string"/>
              <xs:element name="NATIONAL_ID_LOCAL_ACRONYM" type="xs:string"/>
              <xs:element name="CLEARING_SYSTEM" type="xs:string"/>
              <xs:element name="EXAMPLE" type="xs:string"/>
              <xs:element name="LETTER_FORMAT" type="xs:string"/>
              <xs:element name="REGEX_FORMAT" type="xs:string"/>
              <xs:element name="ELEMENTS" type="xs:string"/>
              <xs:element name="LENGTH" type="xs:string"/>
              <xs:element name="LENGTH_IN_DB" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="account_number_format">
          <xs:complexType>
            <xs:sequence minOccurs="0" maxOccurs="unbounded">
              <xs:element name="ISO_COUNTRY_CODE" type="xs:string"/>
              <xs:element name="COUNTRY_NAME" type="xs:string"/>
              <xs:element name="ACCOUNT_NB_TYPE" type="xs:string"/>
              <xs:element name="ACCOUNT_NB_LOCAL_NAME" type="xs:string"/>
              <xs:element name="EXAMPLE" type="xs:string"/>
              <xs:element name="LETTER_FORMAT" type="xs:string"/>
              <xs:element name="REGEX_FORMAT" type="xs:string"/>
              <xs:element name="ELEMENTS" type="xs:string"/>
              <xs:element name="MIN_LENGTH" type="xs:string"/>
              <xs:element name="MAX_LENGTH" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="error">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="code" type="xs:string"/>
              <xs:element name="message" type="xs:string"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Checking your balance

The services endpoint returns every service 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 your api_key and a format (json or xml) and does not use a query.

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

{
   "services": [
      {
         "service_name": "BankSuite",
         "credits": 99009,
         "expiry_date": "2027-09-29",
         "service_expired": 0
      }
   ],
   "errors": []
}

<?xml version="1.0"?>
<result>
   <services>
      <service>
         <service_name>BankSuite</service_name>
         <credits>99009</credits>
         <expiry_date>2027-09-29</expiry_date>
         <service_expired>0</service_expired>
      </service>
   </services>
   <errors/>
</result>

The HTTP status is 200 in every case. With a wrong key, services is empty and errors carries code 301 ({"services":[],"errors":[{"code":"301","message":"API Key is invalid"}]}); without format the body is 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 bank code validation, BIC lookup or structure request uses one query from your Bank Suite balance; requests refused with a request or account error (HTTP 400, 401, 403, 429) do not. Your balance and expiry date are shown under My Services and by the services endpoint.
• 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