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

• 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:

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;
}

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());

	}

}

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);
		}

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

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

<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:

5. SortWare API V4 Status Codes

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

Changelog ( from v3 to v4 ):