Sort Code and Bank Account Validation API V4 Documentation

Developer Integration Reference


This API is part of our SortWare service

1. What is the V4 SortWare API?

The SortWare API provides automation for validating United Kingdom Sort Code and Account Numbers.

The API provides two main functions 'search' and 'validate'. The 'validate' function performs modulus validation given a sort code and account number combination. In case you need to lookup a sort code in the bank directory, you may use the 'search' function and retrieve the bank and branch information for that specific sort code.




2. Features

SortWare API provides some of the following key features:

  • Retrieve information about the bank and branch based on the sort code.
  • Automatically generates a valid IBAN for the supplied sort code and account number
  • Identify support of FPS payments/CHAPS and Direct Debit for the of the bank and branch associated to the supplied sort code.
  • Multiple results displayed in a code-friendly XML and JSON structured response



3. API Usage

This API allows you to automate Sort code and Account Number validation via a single HTTP GET or POST request.

The accepted parameters are listed in the table below:


Field Name Length Type Description
format 4 String This parameter may be one of two supported formats 'xml' or 'json'. Specifies the format of the response.
search 6 String This parameter can be used to search a sort code in our bank directory.
sortcode 6 String The Sort Code provided for validation in combination with the 'account' parameter.
account 8 String Bank Account Number provided for validation in combination with the 'sortcode' parameter.
api_key 128 String Your personal API key used to secure access to the system.

Inside your Client Area -> API Access section you can find your API key, which is used to identify your account during API requests.

We have prepared examples of submitting a POST based request to our API in most common languages:


curl "https://api.iban.com/clients/api/v4/sort/" \
    -X POST \
    -d format=json \
	-d api_key=[YOUR_API_KEY] \
	-d sortcode=200415 \
	-d account=38290008 


<?php
$curl = curl_init();

$post = [
    'format' => 'json',
    'api_key' => '[YOUR_API_KEY]',
    'sortcode'   => '200415',
	'account' => '38290008',
];

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.iban.com/clients/api/v4/sort/',
	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/v4/sort/')

res = Net::HTTP.post_form(uri, "format" => "json", "api_key" => "[YOUR_API_KEY]","sortcode" => "200415","account" => "38290008")

puts res.body


import requests

post_data = {'format':'json', 'api_key':'[YOUR_API_KEY]','sortcode':'200415','account':'38290008'}

response = requests.post('https://api.iban.com/clients/api/v4/sort/',post_data)
print(response.text)


use LWP::UserAgent;

my $ua = LWP::UserAgent->new;
my $server_endpoint = "https://api.iban.com/clients/api/v4/sort/";

my $format = 'json';
my $api_key = '[YOUR_API_KEY]';
my $sortcode = '200415';
my $account = '38290008';


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 . '&sortcode=' . $sortcode . '&account=' . $account;

$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/v4/sort/";
		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&sortcode=200415&account=38290002";

		// 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/v4/sort/");
 
			var postData = "api_key=[YOUR_API_KEY]";
			 postData += "&format=json";
			 postData += "&sortcode=200415";
			 postData += "&account=38290002";
			 
			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/v4/sort/',
    method: 'POST',
    headers: headers,
    form: {'api_key': '[YOUR_API_KEY]', 'format': 'json', 'sortcode': '200415', 'account': '38290002'}
}


request(options, function (error, response, body) {
    if (!error && response.statusCode == 200) {
     
		var data = JSON.parse(body);

		console.log(data.errors);
		
		console.log("Bank Name: " + data.bank_data.bank);
		console.log("Bank BIC: " + data.bank_data.bic);
		console.log("Bank City: " + data.bank_data.city);
		console.log("Bank Address: " + data.bank_data.address);
		console.log("Bank Zip: " + data.bank_data.zip);
		console.log("Bank Phone: " + data.bank_data.phone);
		console.log("Bank Country Name: " + data.bank_data.country);
		console.log("IBAN: " + data.account_data.iban);
		
    }
})





4. API Response Structure

The response of the SortWare V4 API contains a few data objects to help separate the different features of the returned data clearly.
An example of the API response in JSON format can be seen below:

{
	"errors": [],
	"validations": {
		"chars_sortcode": {
			"code": "006",
			"message": "Sort Code does not contain illegal characters"
		},
		"chars_account": {
			"code": "007",
			"message": "Account Number does not contain illegal characters"
		},
		"length_sortcode": {
			"code": "008",
			"message": "Sort Code length is correct"
		},
		"length_account": {
			"code": "009",
			"message": "Account Number length is correct"
		},
		"modulus": {
			"code": "001",
			"message": "Modulus Success: Check digit is valid"
		},
		"sort_found": {
			"code": "002",
			"message": "Sort Code found in bank directory"
		}
	},
	"account_data": {
		"sortcode": "200415",
		"account": "38290008",
		"iban": "GB46BUKB20041538290008"
	},
	"bank_data": {
		"bic": "BUKBGB22XXX",
		"bank": "BARCLAYS BANK UK PLC",
		"branch": "BARCLAYBANK B'CARD N'PTON",
		"address": "Dept AC Barclaycard House ",
		"city": "Northampton",
		"zip": "NN4 7SG",
		"phone": "01604 234234",
		"country": "GB"
	},
	"payment_schemes": {
		"DD": "NO",
		"FPS_PAYMENTS": "YES",
		"CHAPS": "YES",
		"BACS": "YES",
		"CCC_PAYMENTS": "YES"
	}
}


Please feel free to reference the XSD schema for the XML format response below:


<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="result">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="account_data">
          <xs:complexType>
            <xs:sequence>
              <xs:element type="xs:int" name="sortcode"/>
              <xs:element type="xs:int" name="account"/>
              <xs:element type="xs:string" name="iban"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="bank_data">
          <xs:complexType>
            <xs:sequence>
              <xs:element type="xs:string" name="bic"/>
              <xs:element type="xs:string" name="bank"/>
              <xs:element type="xs:string" name="branch"/>
              <xs:element type="xs:string" name="address"/>
              <xs:element type="xs:string" name="city"/>
              <xs:element type="xs:string" name="zip"/>
              <xs:element type="xs:string" name="phone"/>
              <xs:element type="xs:string" name="country"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="payment_schemes">
          <xs:complexType>
            <xs:sequence>
              <xs:element type="xs:string" name="DD"/>
              <xs:element type="xs:string" name="FPS_PAYMENTS"/>
              <xs:element type="xs:string" name="CHAPS"/>
              <xs:element type="xs:string" name="BACS"/>
              <xs:element type="xs:string" name="CCC_PAYMENTS"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="validations">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="modulus">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:short" name="code"/>
                    <xs:element type="xs:string" name="message"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="chars_account">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:byte" name="code"/>
                    <xs:element type="xs:string" name="message"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="chars_sortcode">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:byte" name="code"/>
                    <xs:element type="xs:string" name="message"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="length_sortcode">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:byte" name="code"/>
                    <xs:element type="xs:string" name="message"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="length_account">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:byte" name="code"/>
                    <xs:element type="xs:string" name="message"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element name="sort_found">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:byte" name="code"/>
                    <xs:element type="xs:string" name="message"/>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element type="xs:string" name="errors"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>


Below, you can find detailed descriptions of the types of data elements returned in each individual data object:

Description of the 'account_data' object
Field Name Length Type Description
SORTCODE 6 Integer Returns the sort coded which the client submitted for back reference.
ACCOUNT 8 Integer Contains the submitted account number by the client.
IBAN 125 String Contains the calculated International Bank Account Number ( IBAN ) from the given valid sort code and account number


Description of the 'bank_data' object containing information about the issuing bank and branch of the submitted sort code
Field Name Length Type Description
BIC 8 or 11 String The BIC code of the corresponding bank and branch.
BANK 256 String The name of the bank which owns the submitted sort code.
BRANCH 256 String Name of the specific bank branch which the sort code is assigned to.
ADDRESS 256 String Address of the corresponding bank branch which the sort code belongs to.
CITY 11 String Name of the city in which the respective branch is located.
ZIP 11 String The postal code part of the address of the bank branch.
PHONE 20 String Contact phone number for the respective bank and branch.
COUNTRY 2 String The two letter ISO code of the country which the bank and branch are located.

Description of the 'payment_schemes' object providing information about supported payment schemes

Field Name Length Type Description
DD 3 String Indicator for Direct Debit support of the respective branch. Values may be 'YES' or 'NO'
FPS_PAYMENTS 3 String Indicator for Faster Payments Service (FPS) support of the respective branch. Values may be 'YES' or 'NO'
CHAPS 3 String Indicator for CHAPS payments support of the respective branch. Values may be 'YES' or 'NO'
BACS 3 String Indicator for BACS payment support of the respective branch. Values may be 'YES' or 'NO'
CCC_PAYMENTS 3 String Indicator for Cheque and Credit Clearing Company (C&CCC) payments support of the respective branch. Values may be 'YES' or 'NO'


Description of the 'validations' object
Each validation has it's own reference object which can be easily accessed directly. This is an improvement from our previous version of the API which required looping through the validations array.


Field Name Length Type Description
MODULUS object This is the most important validation done by our system. It uses a specific algorithm for each bank to check if the sort code and account number are valid.
CHARS_ACCOUNT object This validation checks for illegal characters inside the account number.
CHARS_SORTCODE object This validation checks for illegal characters inside the sort code.
LENGTH_SORTCODE object A check for the correct length of the sort code entered. Must be exactly 6 digits.
LENGTH_ACCOUNT object A check for the correct length of the account number. Account Numbers in the UK must not be longer that 8 digits.
SORT_FOUND object This validation reports if the sort code has been found in the official Sort Codes database for the United Kingdom.


Description of the 'errors' object


Field Name Length Type Description
CODE 3 Integer Returns the status code of the error if such has occured. see section 5 ( Status Codes ) for description of the values.
MESSAGE 256 String Contains text description of the current error if such has occured. See section 5 ( status codes ) for all possible results.



5. SortWare API V4 Status Codes

There are two types of status codes returned by the API.

  • Validation success or fail are returned in the 'validations' data object.
  • Account errors are returned in the 'errors' object.


Status Code Type Description
301 Account Error API Key is invalid
302 Account Error Subscription expired
303 Account Error No queries available
304 Account Error You have no access to this API
305 Account Error IP Address not allowed
201 Validation Failed Modulus Failed: Check digit is not valid
202 Validation Failed Sort Code not found in bank directory
206 Validation Failed Sort Code contains illegal characters
207 Validation Failed Account Number contains illegal characters
208 Validation Failed Sort Code length is not correct
209 Validation Failed Account Number length is not correct
001 Validation Success Modulus Success: Check digit is valid
002 Validation Success Sort Code not found in bank directory
006 Validation Success Sort Code does not contain illegal characters
007 Validation Success Account Number does not contain illegal characters
008 Validation Success Sort Code length is correct
009 Validation Success Account Number length is correct



Changelog ( from v3 to v4 ):


New response structure
The new version of the SortWare API now provides improved response structure in both XML and JSON formatting.
We have separated the results in five elements ( account_data, bank_data, payment_schemas, validations and errors )
The structure is very similar to our IBAN Validation API making it easier to integrate when using both of our solutions. You may find a detailed description of the response structure below ( see section 4. API Response Structure )

Error Codes
Error codes have been implemented in the response of the SortWare V4 to provide easier parsing of validation results and API responses.
As with our other APIs error codes return machine readable formatting for all errors the V4 API may encounter.
See section 5. (Error Codes) for detailed description of the error codes returned by the system.

Improved IBAN Calculation Functionality
We have introduced a new and improved algorithm for calculating IBAN from Sort Code and Account Number data for both United Kingdom and Ireland.
The new functionality uses our accurate bank code directory to calculate IBANs with higher precision and decreased possibility of errors during calculation.