EN
Bank Suite API Documentation
This API is part of our Bank Suite service
1. Introduction
The Bank Suite is a web service which provides validation capabilities for bank codes and account numbers.
Designed mainly to provide bank code and account number validation for countries which do not use the IBAN standard (see list of countries ).
Powered by the one of the largest and up to date bank code directories in the industry it is a powerful suit of services helping businesses improve the quality of international payments
2. Features
Some of the key features and benefits of the Bank Suite service are:
- Global Coverage
- Validate Bank Codes for non-IBAN countries
- Validate domestic bank code and account number check digits
- Monthly updated world bank directory covering 195 countries
- Query the bank suite directory by Bank Code(National ID)
- Query the bank suite directory by BIC code
- Validate Bank Code structure
- Validate Bank Code length
- Identify BIC code related to bank routing/sorting code
3. API Endpoints
The Bank Suite API provides the following endpoints:
Main Endpoint - Validate bank code (NID)
http://api.iban.com/clients/api/banksuite/nid/
This endpoint is used to validate bank codes and retrieve information about the bank and branch they belong.
It also provides an additional feature to validate bank account numbers by checking their structure, formatting, length and check digit.
BIC Endpoint - Search by BIC Code
http://api.iban.com/clients/api/banksuite/bic/
This endpoint performs validation on a provided BIC code and performs a search in our banking directory.
If the BIC is currently active and in use, the system will provide bank code and bank and branch information related to this BIC
Structure Endpoint - Information about format and structure.
http://api.iban.com/clients/api/banksuite/structure/
The structure endpoint provides information about bank code and account number structure for each specific country.
4. Bank Code API Input
The REST API accepts both HTTP GET or POST requests.The input parameters are listed in the table below:
| Field Name | Length | Type | Description |
|---|---|---|---|
| nid | Max 15 | String | The Bank Code sent to our system for validation. |
| account | Max 50 | String | (optional) Account number sent for validation. |
| country_iso | Max 2 | String | 2 letter ISO Code of the country. List of supported countries in Section 8. Supported Countries |
| api_key | 128 | String | Your personal API key. |
| format | 5 | String | Format of the response XML and JSON supported. |
*To obtain an API key, please contact us at contact@iban.com or purchase a subscription at our order page
EXAMPLE – Validate a Bank Code
Feel free to use the sample code below to test the API in the most common programming languages.
curl "https://api.iban.com/clients/api/banksuite/nid/" \
-X POST \
-d format=json \
-d api_key=[YOUR_API_KEY] \
-d country_iso=US
-d nid=322271627
<?php
$curl = curl_init();
$post = [
'format' => 'json',
'api_key' => '[YOUR_API_KEY]',
'country_iso' => 'US',
'nid' => '322271627'
];
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.iban.com/clients/api/banksuite/nid/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $post
));
$output = curl_exec($curl);
$result = json_decode($output);
print_r($result);
curl_close($curl);
?>
require 'net/http'
uri = URI('https://api.iban.com/clients/api/banksuite/')
res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","country_iso" => "US","nid" => "322271627")
puts res.body
import requests
post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','country_iso':'US','nid':'322271627'}
response = requests.post('https://api.iban.com/clients/api/banksuite/nid/',post_data)
print(response.text)
use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/banksuite/nid/";
my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $country_iso = 'US';
my $nid = '322271627';
my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');
my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&country_iso=' . $country_iso . '&nid=' . $nid;
$req->content($post_data);
my $resp = $ua->request($req);
if ( $resp->is_success ) {
my $message = $resp->decoded_content;
print $message;
}
JAVA
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;
public class ibanapi {
private final String USER_AGENT = "API Client/1.0";
public static void main(String[] args) throws Exception {
ibanapi http = new ibanapi();
System.out.println("\nTesting API - Send API POST request");
http.sendPost();
}
// HTTP POST request
private void sendPost() throws Exception {
String url = "https://api.iban.com/clients/api/banksuite/nid/";
URL obj = new URL(url);
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
//add reuqest header
con.setRequestMethod("POST");
con.setRequestProperty("User-Agent", USER_AGENT);
con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");
String urlParameters = "api_key=[YOUR_API_KEY]&format=json&country_iso=US&nid=322271627";
// Send post request
con.setDoOutput(true);
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
wr.writeBytes(urlParameters);
wr.flush();
wr.close();
int responseCode = con.getResponseCode();
System.out.println("\nSending 'POST' request to URL : " + url);
System.out.println("Post parameters : " + urlParameters);
System.out.println("Response Code : " + responseCode);
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
//print result
System.out.println(response.toString());
}
}
.NET
public static void Main(string[] args)
{
var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/banksuite/nid/");
var postData = "api_key=[YOUR_API_KEY]";
postData += "&format=json";
postData += "&country_iso=US";
postData += "&nid=322271627";
var data = Encoding.ASCII.GetBytes(postData);
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = data.Length;
using (var stream = request.GetRequestStream())
{
stream.Write(data, 0, data.Length);
}
var response = (HttpWebResponse)request.GetResponse();
var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
Console.WriteLine(responseString);
Console.Write("Press any key to continue . . . ");
Console.ReadKey(true);
}
NODE
var request = require('request');
var headers = {
'User-Agent': 'IBAN API Client/0.0.1',
'Content-Type': 'application/x-www-form-urlencoded'
}
var options = {
url: 'https://api.iban.com/clients/api/banksuite/nid/',
method: 'POST',
headers: headers,
form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'country_iso': 'US', 'nid': '322271627'}
}
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
var data = JSON.parse(body);
console.log(data.error);
console.log("Query Status: " + data.success);
console.log("Bank Code Valid: " + data.nid_valid);
console.log("Bank Name: " + data.directory_results.institution_name);
console.log("Bank BIC: " + data.directory_results.bic);
}
})
An example usage of the BankSuite API with a GET request can be:
https://api.iban.com/clients/api/banksuite/nid/?format=json&api_key=[API_KEY]&country_iso=US&nid=322271627
Where:
- key is your API key
- NID is the bank code sent for validation by the API module.
- xml is the response format. Also a json keyword can be specified for json formatted response.
Once an HTTP GET or POST request is made with the correct API key, the system will return the results in the specified format.
4.1 Bank Code API Output
An XSD Schema of the API’s response can be found below:XSD Schema for NID endpoint: download
The API results are delivered in JSON or XML format for maximum usability. Find below descriptions for the JSON properties returned by the API:
| Object | Type | Description |
|---|---|---|
| QUERY | Array | Contains the user supplied input parameters. |
| SUCCESS | Boolean | Indicates a true or false indicating if the query succeeded |
| ACCOUNT_VALID | Boolean | True or False. Indicates if the account number supplied has passed all validations |
| NID_VALID | Boolean | True or False. Indicates if the bank code has passed all validations |
| RECORDS_FOUND | Integer | Indicates the number of records found in the bank directory. If more than one, you may use the 'limit' parameter to retrieve multiple records for the same bank code |
| RECORDS_DISPLAYED | Integer | Indicates the number of records displayed in the 'directory_results' object. By default we display one record. With the 'limit' parameter, you can retrieve multiple |
| DIRECTORY_RESULTS | Array | This object contains the data retrieved from our bank directory for the respective bank code. You may find a detailed description of this object in Section 7 Data Field Definitions |
| ERROR | Object | Provides error code and description if an error occurs. For descriptions, please refer to Section 4.2 Bank Code API Errors |
A sample JSON reply from the API for a IBAN validation query would be:
{
"query": {
"country_iso": "DE",
"nid": "37040044",
"account": "3901190310"
},
"success": true,
"account_valid": false,
"nid_valid": true,
"records_found": "17",
"records_displayed": 1,
"directory_results": [
{
"office_type": "DB",
"legal_type": "B",
"institution_status": "BANK",
"iso_lei_code": "",
"bic8": "COBADEFF",
"branch_bic": "366",
"bic": "COBADEFF366",
"chips_uid": "",
"national_id": "37040044",
"connected_bic": "COBADEFF366",
"institution_name": "COMMERZBANK AG",
"branch_information": "Commerzbank Pulheim",
"pob_number": "",
"street_address_1": "KAISERSTRASSE 16",
"street_address_2": "",
"street_address_3": "",
"street_address_4": "",
"city": "FRANKFURT AM MAIN",
"cps": "HESSE",
"zip_code": "60261",
"country_name": "GERMANY",
"iso_country_code": "DE",
"subtype_indicator": "SUPE",
"network_connectivity": "CNN",
"service_codes": "EBAERPFINTG+"
}
],
"error": {
"code": "813",
"message": "Invalid Account Check Digit"
}
}
4.2 Bank Code API Errors
We utilize two types of errors for this endpoint."Query Failed" error indicates that validations were not carried out.
"Validation failed" error indicates that the bank code or account number submitted has failed a validation step.
| Error Code | HTTP Status Code | Type | Message |
|---|---|---|---|
| 301 | 403 | Query failed | API Key is invalid |
| 305 | 403 | Query failed | IP Address not allowed |
| 304 | 403 | Query failed | You have no access to this API |
| 302 | 403 | Query failed | Subscription expired |
| 303 | 403 | Query failed | No queries available |
| 306 | 400 | Query failed | Bad Request. Required minimum parameters: api_key; format; iso; nid |
| 806 | 400 | Query failed | Invalid value for 'limit' parameter |
| 500 | 500 | Query failed | Internal Server Error |
| 801 | 200 | Validation failed | Invalid Characters in NID |
| 802 | 200 | Validation failed | Country ISO code invalid |
| 803 | 200 | Validation failed | Unsupported country ISO code |
| 804 | 200 | Validation failed | NID length is not correct for US Accepted length for US: 9 characters. |
| 805 | 200 | Validation failed | Invalid NID format. Example: 211770093 |
| 400 | 200 | Validation failed | BankCode(NID) not found in the official directory |
| 809 | 200 | Validation failed | Invalid Characters in account |
| 810 | 200 | Validation failed | Country ISO code invalid |
| 811 | 200 | Validation failed | Account Number length is not correct for US |
| 812 | 200 | Validation failed | Invalid Account format. Example: 39581126 |
| 813 | 200 | Validation failed | Invalid Account Check Digit |
| 814 | 200 | Validation failed | Invalid Bank Code/NID Check Digit |
5. BIC API Input
The BIC Code endpoint is designed to locate a bank code from a given BIC code in the Bank Suite directory.The input parameters are listed in the table below:
| Field Name | Length | Type | Description |
|---|---|---|---|
| bic | Max 11 | String | The BIC sent to our system for validation and identification. |
| api_key | 128 | String | Your personal API key. |
| format | 5 | String | Format of the response XML and JSON supported. |
*To obtain an API key, please contact us at contact@iban.com or purchase a subscription at our order page
EXAMPLE – Validate and lookup BIC
Feel free to use the sample code below to test the API in the most common programming languages.
curl "https://api.iban.com/clients/api/banksuite/bic/" \
-X POST \
-d format=json \
-d api_key=[YOUR_API_KEY] \
-d bic=BARCGB22XXX
<?php
$curl = curl_init();
$post = [
'format' => 'json',
'api_key' => '[YOUR_API_KEY]',
'bic' => 'BARCGB22XXX'
];
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.iban.com/clients/api/banksuite/bic/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $post
));
$output = curl_exec($curl);
$result = json_decode($output);
print_r($result);
curl_close($curl);
?>
require 'net/http'
uri = URI('https://api.iban.com/clients/api/banksuite/bic/')
res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","bic" => "BARCGB22XXX")
puts res.body
import requests
post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','bic':'BARCGB22XXX'}
response = requests.post('https://api.iban.com/clients/api/banksuite/bic/',post_data)
print(response.text)
use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/banksuite/bic/";
my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $bic = 'BARCGB22XXX';
my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');
my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&bic=' . $bic;
$req->content($post_data);
my $resp = $ua->request($req);
if ( $resp->is_success ) {
my $message = $resp->decoded_content;
print $message;
}
JAVA
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;
public class ibanapi {
private final String USER_AGENT = "API Client/1.0";
public static void main(String[] args) throws Exception {
ibanapi http = new ibanapi();
System.out.println("\nTesting API - Send API POST request");
http.sendPost();
}
// HTTP POST request
private void sendPost() throws Exception {
String url = "https://api.iban.com/clients/api/banksuite/bic/";
URL obj = new URL(url);
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
//add reuqest header
con.setRequestMethod("POST");
con.setRequestProperty("User-Agent", USER_AGENT);
con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");
String urlParameters = "api_key=[YOUR_API_KEY]&format=json&bic=BARCGB22XXX";
// Send post request
con.setDoOutput(true);
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
wr.writeBytes(urlParameters);
wr.flush();
wr.close();
int responseCode = con.getResponseCode();
System.out.println("\nSending 'POST' request to URL : " + url);
System.out.println("Post parameters : " + urlParameters);
System.out.println("Response Code : " + responseCode);
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
//print result
System.out.println(response.toString());
}
}
.NET
public static void Main(string[] args)
{
var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/banksuite/bic/");
var postData = "api_key=[YOUR_API_KEY]";
postData += "&format=json";
postData += "&bic=BARCGB22XXX";
var data = Encoding.ASCII.GetBytes(postData);
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = data.Length;
using (var stream = request.GetRequestStream())
{
stream.Write(data, 0, data.Length);
}
var response = (HttpWebResponse)request.GetResponse();
var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
Console.WriteLine(responseString);
Console.Write("Press any key to continue . . . ");
Console.ReadKey(true);
}
NODE
var request = require('request');
var headers = {
'User-Agent': 'IBAN API Client/0.0.1',
'Content-Type': 'application/x-www-form-urlencoded'
}
var options = {
url: 'https://api.iban.com/clients/api/banksuite/bic/',
method: 'POST',
headers: headers,
form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'bic': 'BARCGB22XXX'}
}
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
var data = JSON.parse(body);
console.log(data.error);
console.log("Query Status: " + data.success);
console.log("Bank Code Valid: " + data.bic_valid);
console.log("Bank Name: " + data.directory_results.institution_name);
console.log("Bank BIC: " + data.directory_results.bic);
}
})
An example usage of the BankSuite API with a GET request can be:
https://api.iban.com/clients/api/banksuite/bic/?format=json&api_key=[API_KEY]&bic=BARCGB22XXX
Where:
- key is your API key
- BIC code sent for validation by the API module.
- xml is the response format. Also a json keyword can be specified for json formatted response.
Once an HTTP GET or POST request is made with the correct API key, the system will return the results in the specified format.
5.1 BIC API Output
An XSD Schema of the API’s response can be found below:XSD Schema for BIC endpoint: download
The API results are delivered in JSON or XML format for maximum usability. Find below descriptions for the JSON properties returned by the API:
| Object | Type | Description |
|---|---|---|
| QUERY | Array | Contains the user supplied input parameters. |
| SUCCESS | Boolean | Indicates a true or false indicating if the query succeeded |
| BIC_VALID | Boolean | True or False. Indicates if the submitted BIC have passed all validations |
| RECORDS_FOUND | Integer | Indicates the number of records found in the bank directory. If more than one, you may use the 'limit' parameter to retrieve multiple records for the same bank code |
| RECORDS_DISPLAYED | Integer | Indicates the number of records displayed in the 'directory_results' object. By default we display one record. With the 'limit' parameter, you can retrieve multiple |
| DIRECTORY_RESULTS | Array | This object contains the data retrieved from our bank directory for the respective bank code. You may find a detailed description of this object in Section 7 Data Field Definitions |
| ERROR | Object | Provides error code and description if an error occurs. For descriptions, please refer to Section 5.2 BIC API Errors |
A sample JSON reply from the API for a IBAN validation query would be:
{
"query": {
"bic": "CHASUS33CON"
},
"success": true,
"bic_valid": true,
"records_found": "1",
"records_displayed": 1,
"directory_results": [
{
"office_type": "DB",
"legal_type": "B",
"institution_status": "BANK",
"iso_lei_code": "",
"bic8": "CHASUS33",
"branch_bic": "CON",
"bic": "CHASUS33CON",
"chips_uid": "",
"national_id": "",
"connected_bic": "CHASUS33CON",
"institution_name": "JPMORGAN CHASE BANK, N.A.",
"branch_information": "",
"pob_number": "",
"street_address_1": "",
"street_address_2": "",
"street_address_3": "",
"street_address_4": "",
"city": "NEW YORK",
"cps": "NY",
"zip_code": "",
"country_name": "UNITED STATES OF AMERICA",
"iso_country_code": "US",
"subtype_indicator": "SUPE",
"network_connectivity": "CNN",
"service_codes": "EB+FIN"
}
]
}
5.2 BIC API Errors
We utilize two types of errors for this endpoint."Query Failed" error indicates that validations were not carried out.
"Validation failed" error indicates that the bank code or account number submitted has failed a validation step.
| Error Code | HTTP Status Code | Type | Message |
|---|---|---|---|
| 301 | 403 | Query failed | API Key is invalid |
| 305 | 403 | Query failed | IP Address not allowed |
| 304 | 403 | Query failed | You have no access to this API |
| 302 | 403 | Query failed | Subscription expired |
| 303 | 403 | Query failed | No queries available |
| 306 | 400 | Query failed | Bad Request. Required minimum parameters: api_key; format; iso; nid |
| 806 | 400 | Query failed | Invalid value for 'limit' parameter |
| 500 | 500 | Query failed | Internal Server Error |
| 807 | 200 | Validation failed | Invalid Characters in BIC |
| 808 | 200 | Validation failed | BIC length is not correct. BIC code must be 8 or 11 characters long |
| 400 | 200 | Validation failed | BIC not found in official directory |
6. STRUCTURE API Input
The Structure endpoint is designed to provide bank code formatting information for a specified country code.The input parameters are listed in the table below:
| Field Name | Length | Type | Description |
|---|---|---|---|
| country_iso | 2 | String | The 2 letter ISO country code submitted by the client |
| api_key | 128 | String | Your personal API key. |
| format | 5 | String | Format of the response XML and JSON supported. |
*To obtain an API key, please contact us at contact@iban.com or purchase a subscription at our order page
EXAMPLE – Retrieve Bank Code and Account Number format and structure for a specified country
Feel free to use the sample code below to integrate the API in the most common programming languages.
curl "https://api.iban.com/clients/api/banksuite/structure/" \
-X POST \
-d format=json \
-d api_key=[YOUR_API_KEY] \
-d country_iso=US
<?php
$curl = curl_init();
$post = [
'format' => 'json',
'api_key' => '[YOUR_API_KEY]',
'country_iso' => 'US',
];
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.iban.com/clients/api/banksuite/structure/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POSTFIELDS => $post
));
$output = curl_exec($curl);
$result = json_decode($output);
print_r($result);
curl_close($curl);
?>
require 'net/http'
uri = URI('https://api.iban.com/clients/api/banksuite/')
res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","country_iso" => "US")
puts res.body
import requests
post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','country_iso':'US'}
response = requests.post('https://api.iban.com/clients/api/banksuite/structure/',post_data)
print(response.text)
use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/banksuite/structure/";
my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $country_iso = 'US';
my $req = HTTP::Request->new( POST => $server_endpoint );
$req->content_type('application/x-www-form-urlencoded');
my $post_data = 'format=' . $format . '&api_key=' . $api_key . '&country_iso=' . $country_iso ;
$req->content($post_data);
my $resp = $ua->request($req);
if ( $resp->is_success ) {
my $message = $resp->decoded_content;
print $message;
}
JAVA
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
import org.json.simple.JSONObject;
import org.json.simple.JSONArray;
import org.json.simple.parser.ParseException;
import org.json.simple.parser.JSONParser;
public class ibanapi {
private final String USER_AGENT = "API Client/1.0";
public static void main(String[] args) throws Exception {
ibanapi http = new ibanapi();
System.out.println("\nTesting API - Send API POST request");
http.sendPost();
}
// HTTP POST request
private void sendPost() throws Exception {
String url = "https://api.iban.com/clients/api/banksuite/structure/";
URL obj = new URL(url);
HttpsURLConnection con = (HttpsURLConnection) obj.openConnection();
//add reuqest header
con.setRequestMethod("POST");
con.setRequestProperty("User-Agent", USER_AGENT);
con.setRequestProperty("Accept-Language", "en-US,en;q=0.5");
String urlParameters = "api_key=[YOUR_API_KEY]&format=json&country_iso=US";
// Send post request
con.setDoOutput(true);
DataOutputStream wr = new DataOutputStream(con.getOutputStream());
wr.writeBytes(urlParameters);
wr.flush();
wr.close();
int responseCode = con.getResponseCode();
System.out.println("\nSending 'POST' request to URL : " + url);
System.out.println("Post parameters : " + urlParameters);
System.out.println("Response Code : " + responseCode);
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
//print result
System.out.println(response.toString());
}
}
.NET
public static void Main(string[] args)
{
var request = (HttpWebRequest)WebRequest.Create("https://api.iban.com/clients/api/banksuite/structure/");
var postData = "api_key=[YOUR_API_KEY]";
postData += "&format=json";
postData += "&country_iso=US";
var data = Encoding.ASCII.GetBytes(postData);
request.Method = "POST";
request.ContentType = "application/x-www-form-urlencoded";
request.ContentLength = data.Length;
using (var stream = request.GetRequestStream())
{
stream.Write(data, 0, data.Length);
}
var response = (HttpWebResponse)request.GetResponse();
var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
Console.WriteLine(responseString);
Console.Write("Press any key to continue . . . ");
Console.ReadKey(true);
}
NODE
var request = require('request');
var headers = {
'User-Agent': 'IBAN API Client/0.0.1',
'Content-Type': 'application/x-www-form-urlencoded'
}
var options = {
url: 'https://api.iban.com/clients/api/banksuite/structure/',
method: 'POST',
headers: headers,
form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'country_iso': 'US'}
}
request(options, function (error, response, body) {
if (!error && response.statusCode == 200) {
var data = JSON.parse(body);
console.log(data.error);
console.log("Query Status: " + data.success);
console.log("Bank Code Valid: " + data.national_id_format.LENGTH);
}
})
An example usage of the BankSuite API with a GET request can be:
https://api.iban.com/clients/api/banksuite/structure/?format=json&api_key=[API_KEY]&country_iso=GB
Where:
- key is your API key
- country_iso is the 2 letter ISO country code you need the formatting data for.
- xml is the response format. Also a json keyword can be specified for json formatted response.
Once an HTTP GET or POST request is made with the correct API key, the system will return the results in the specified format.
6.1 Structure API Output
An XSD Schema of the API’s response can be found below:XSD Schema for Structure endpoint: download
The API results are delivered in JSON or XML format for maximum usability. Find below descriptions for the JSON properties returned by the API:
| Object | Type | Description |
|---|---|---|
| success | Boolean | Indicates a true or false indicating if the query succeeded |
| national_id_format | Object | This object contains data for the format and structure of the Bank Code |
| account_number_format | Object | This object contains information about the structure, length and formatting of the domestic bank account number for the specified country. |
| error | Object | Provides error code and description if an error occurs. For descriptions, please refer to Section 6.2 Structure API Errors |
A sample JSON reply from the API for a IBAN validation query would be:
{
"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",
"ELEMENTS": "BANK_CODE,INSTITUTION_CODE,CHECKSUM",
"LENGTH": "9",
"LENGTH_IN_DB": "9"
}
],
"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": "1000248938",
"LETTER_FORMAT": "AAAAAAAAAA",
"ELEMENTS": "ACCOUNT",
"MIN_LENGTH": "9",
"MAX_LENGTH": "10"
}
]
}
6.2 Structure API Errors
The structure endpoint can return any of the following errors:| Error Code | HTTP Status Code | Type | Message |
|---|---|---|---|
| 301 | 403 | Query failed | API Key is invalid |
| 305 | 403 | Query failed | IP Address not allowed |
| 304 | 403 | Query failed | You have no access to this API |
| 302 | 403 | Query failed | Subscription expired |
| 303 | 403 | Query failed | No queries available |
| 306 | 400 | Query failed | Bad Request. Required minimum parameters: api_key; format; iso; nid |
| 806 | 400 | Query failed | Invalid value for 'limit' parameter |
| 500 | 500 | Query failed | Internal Server Error |
| 802 | 400 | Query failed | Country ISO code invalid |
| 400 | 400 | Query failed | ISO Country Code not found in registry |
7. Data Field Definitions
The data field definitions section is only available for licensed users.
To purchase a license for the Bank Suite service, please visit our pricing page
8. Supported Countries
The table below provides a quick reference of the countries which the Bank Suite service covers.
| ISO | Country | Account validation | Length |
|---|---|---|---|
| AD | ANDORRA | n/a | 8 |
| AE | UNITED ARAB EMIRATES | n/a | 3 and 9 |
| AF | AFGHANISTAN | n/a | 4 |
| AG | ANTIGUA AND BARBUDA | n/a | 8 |
| AI | ANGUILLA | n/a | 8 |
| AL | ALBANIA | n/a | 8 |
| AM | ARMENIA | n/a | 5 |
| AO | ANGOLA | n/a | 8 |
| AR | ARGENTINA | n/a | 7 |
| AS | AMERICAN SAMOA | n/a | 9 |
| AT | AUSTRIA | yes | 5 |
| AU | AUSTRALIA | n/a | 6 |
| AW | ARUBA | n/a | 9 |
| AZ | AZERBAIJAN | n/a | 6 and 12 |
| BA | BOSNIA AND HERZEGOVINA | yes | 6 |
| BD | BANGLADESH | n/a | 9 |
| BE | BELGIUM | yes | 3 |
| BF | BURKINA FASO | n/a | 5 |
| BG | BULGARIA | n/a | 8 |
| BH | BAHRAIN | n/a | 4 |
| BJ | BENIN | n/a | 5 |
| BM | BERMUDA | n/a | 2 |
| BN | BRUNEI DARUSSALAM | n/a | 6 |
| BO | BOLIVIA | n/a | 5 |
| BR | BRAZIL | n/a | 7 and 8 |
| BS | BAHAMAS | n/a | 8 |
| BT | BHUTAN | n/a | 9 |
| BW | BOTSWANA | n/a | 6 |
| BY | BELARUS | n/a | 8 and 11 |
| BZ | BELIZE | n/a | 8 |
| CA | CANADA | n/a | 9 |
| CF | CENTRAL AFRICAN REPUBLIC | n/a | 10 |
| CG | CONGO | n/a | 10 |
| CH | SWITZERLAND | yes | 5 |
| CI | COTE D'IVOIRE | n/a | 5 |
| CK | COOK ISLANDS | n/a | 6 |
| CL | CHILE | n/a | 3 |
| CM | CAMEROON | n/a | 10 |
| CN | CHINA | n/a | 12 |
| CO | COLOMBIA | n/a | 2 and 5 |
| CR | COSTA RICA | yes | 3 |
| CV | CABO VERDE | n/a | 2 and 8 |
| CY | CYPRUS | n/a | 8 |
| CZ | CZECHIA | yes | 4 |
| DE | GERMANY | yes | 8 |
| DK | DENMARK | yes | 4 |
| DM | DOMINICA | n/a | 8 |
| DO | DOMINICAN REPUBLIC | n/a | 4 |
| DZ | ALGERIA | n/a | 3 |
| EC | ECUADOR | n/a | 2 and 8 |
| EE | ESTONIA | yes | 2 |
| ES | SPAIN | yes | 9 |
| FI | FINLAND | yes | 3 |
| FJ | FIJI | n/a | 6 |
| FO | FAROE ISLANDS | yes | 4 |
| FR | FRANCE | yes | 10 |
| GA | GABON | n/a | 10 |
| GB | UNITED KINGDOM | yes | 6 |
| GD | GRENADA | n/a | 8 |
| GE | GEORGIA | n/a | 2 and 9 |
| GF | FRENCH GUIANA | yes | 10 |
| GG | GUERNSEY | yes | 6 |
| GH | GHANA | n/a | 6 |
| GI | GIBRALTAR | n/a | 6 |
| GL | GREENLAND | yes | 4 |
| GM | GAMBIA | n/a | 6 |
| GN | GUINEA | n/a | 6 |
| GP | GUADELOUPE | yes | 10 |
| GQ | EQUATORIAL GUINEA | n/a | 10 |
| GR | GREECE | n/a | 7 |
| GT | GUATEMALA | n/a | 2 |
| GU | GUAM | n/a | 9 |
| GW | GUINEA-BISSAU | n/a | 5 |
| GY | GUYANA | n/a | 8 |
| HK | HONG KONG | n/a | 6 |
| HN | HONDURAS | n/a | 6 |
| HR | CROATIA | yes | 7 |
| HT | HAITI | n/a | 9 |
| HU | HUNGARY | yes | 8 |
| ID | INDONESIA | n/a | 7 |
| IE | IRELAND | yes | 6 |
| IL | ISRAEL | yes | 6 |
| IM | ISLE OF MAN | yes | 6 |
| IN | INDIA | n/a | 9 and 11 |
| IS | ICELAND | yes | 4 |
| IT | ITALY | yes | 10 |
| JE | JERSEY | yes | 6 |
| JM | JAMAICA | n/a | 8 |
| JO | JORDAN | n/a | 2 |
| JP | JAPAN | n/a | 7 |
| KE | KENYA | n/a | 5 |
| KG | KYRGYZSTAN | n/a | 6 |
| KH | CAMBODIA | n/a | 6 |
| KM | COMOROS | n/a | 5 |
| KN | SAINT KITTS AND NEVIS | n/a | 8 |
| KR | REPUBLIC OF KOREA | n/a | 7 |
| KW | KUWAIT | n/a | 4 |
| KZ | KAZAKHSTAN | n/a | 3 |
| LB | LEBANON | n/a | 4 |
| LC | SAINT LUCIA | n/a | 8 |
| LI | LIECHTENSTEIN | yes | 5 |
| LK | SRI LANKA | n/a | 7 |
| LS | LESOTHO | n/a | 6 |
| LT | LITHUANIA | n/a | 5 |
| LU | LUXEMBOURG | n/a | 3 |
| LV | LATVIA | n/a | 4 |
| MA | MOROCCO | yes | 10 |
| MC | MONACO | yes | 10 |
| MD | MOLDOVA | n/a | 11 |
| ME | MONTENEGRO | yes | 3 |
| MG | MADAGASCAR | n/a | 10 |
| MK | NORTH MACEDONIA | yes | 3 |
| ML | MALI | n/a | 5 |
| MN | MONGOLIA | n/a | 6 |
| MO | MACAO | n/a | 3 |
| MP | NORTHERN MARIANA ISLANDS | n/a | 9 |
| MQ | MARTINIQUE | yes | 10 |
| MR | MAURITANIA | yes | 10 |
| MS | MONTSERRAT | n/a | 8 |
| MT | MALTA | n/a | 5 |
| MU | MAURITIUS | n/a | 4 |
| MW | MALAWI | n/a | 6 |
| MX | MEXICO | n/a | 6 |
| MY | MALAYSIA | n/a | 4 and 9 |
| MZ | MOZAMBIQUE | n/a | 2 |
| NA | NAMIBIA | n/a | 6 |
| NC | NEW CALEDONIA | yes | 10 |
| NE | NIGER | n/a | 5 |
| NG | NIGERIA | n/a | 9 |
| NI | NICARAGUA | n/a | 2 |
| NL | NETHERLANDS | yes | 4 |
| NO | NORWAY | yes | 4 |
| NP | NEPAL | n/a | 8 |
| NZ | NEW ZEALAND | n/a | 6 |
| PA | PANAMA | n/a | 3 and 9 |
| PE | PERU | n/a | 3 |
| PF | FRENCH POLYNESIA | yes | 10 |
| PG | PAPUA NEW GUINEA | n/a | 6 |
| PH | PHILIPPINES | n/a | 6 and 9 |
| PK | PAKISTAN | n/a | 7 |
| PL | POLAND | yes | 8 |
| PM | SAINT PIERRE AND MIQUELON | yes | 10 |
| PR | PUERTO RICO | n/a | 9 |
| PS | PALESTINE | n/a | 2 and 5 |
| PT | PORTUGAL | yes | 8 |
| PY | PARAGUAY | n/a | 4 and 7 |
| QA | QATAR | n/a | 2 |
| RE | REUNION | yes | 10 |
| RO | ROMANIA | n/a | 4 |
| RS | SERBIA | yes | 3 |
| RU | RUSSIAN FEDERATION | yes | 9 |
| RW | RWANDA | n/a | 3 |
| SA | SAUDI ARABIA | n/a | 2 |
| SB | SOLOMON ISLANDS | n/a | 6 |
| SC | SEYCHELLES | n/a | 6 |
| SE | SWEDEN | yes | 4 |
| SG | SINGAPORE | n/a | 7 |
| SI | SLOVENIA | yes | 5 |
| SK | SLOVAKIA | yes | 4 |
| SL | SIERRA LEONE | n/a | 6 |
| SM | SAN MARINO | yes | 10 |
| SN | SENEGAL | n/a | 5 |
| ST | SAO TOME AND PRINCIPE | n/a | 8 |
| SV | EL SALVADOR | n/a | 2 |
| SZ | ESWATINI | n/a | 6 |
| TD | CHAD | n/a | 10 |
| TG | TOGO | n/a | 5 |
| TH | THAILAND | n/a | 7 |
| TJ | TAJIKISTAN | n/a | 9 |
| TL | TIMOR-LESTE | yes | 4 |
| TN | TUNISIA | yes | 5 |
| TO | TONGA | n/a | 6 |
| TR | TURKEY | n/a | 9 |
| TW | TAIWAN | n/a | 7 |
| TZ | TANZANIA | n/a | 6 |
| UA | UKRAINE | n/a | 6 |
| UG | UGANDA | n/a | 6 |
| US | UNITED STATES OF AMERICA | n/a | 9 |
| UY | URUGUAY | n/a | 3 |
| UZ | UZBEKISTAN | n/a | 5 |
| VA | HOLY SEE | n/a | 3 |
| VC | SAINT VINCENT AND THE GRENADINES | n/a | 8 |
| VE | VENEZUELA (BOLIVARIAN REPUBLIC OF) | n/a | 4 |
| VI | VIRGIN ISLANDS (U.S.) | n/a | 9 |
| VN | VIET NAM | n/a | 8 |
| VU | VANUATU | n/a | 6 |
| WF | WALLIS AND FUTUNA | yes | 10 |
| WS | SAMOA | n/a | 6 |
| XK | REPUBLIC OF KOSOVO | yes | 4 |
| YT | MAYOTTE | yes | 10 |
| ZA | SOUTH AFRICA | n/a | 6 |
| ZM | ZAMBIA | n/a | 6 |
| ZW | ZIMBABWE | n/a | 5 |