API Flow Bank Name Search

Flow diagram Name Search


We have kept the flow simple

  1. Request a security token for every new validation
  2. Enter the bank name and location
  3. Use the bankToken and freeToken from the response and add the account number
  4. Check what additional data and validations are available
  5. Get the freeToken and bankToken
  6. Use those tokens to additional details or perform additional validations free of charge

This flow is covered below with links to more details:

1. Security token

Create a Security Token for each new validation you do.


2. Validate the bank details

Search for the bank and branch by name


Understanding the response

Here is a quick run through the response so you know what we’re responding with

Search Criteria

The first three fields in the response show you your search criteria you that were entered.

“countryCode”: “GB”,

“nationalId”: “LOYDGB2LXXX”,

“accountNumber”: “”,


The next section shows you what we recommend.

The recommendations can be changed self-service hub by signing in as an administrator at the URL below


and going to the bottom left and using the “recommendations” section.  The recommendations are set to International or cross border as default.

If in this case you made GB a domestic currency we would recommend back a sort code and account number for the UK as domestically we use sort code and account number and not a IBAN.  We do this globally.

“recommendedNatId”: “”,

“recommendedAcct”: “GB50LOYD30940801638696”,

“recommendedBIC”: “LOYDGB21124”,

Validation Status and Errors

The next fields are status and comment which tell you if the search was PASS, CAUTION or FAIL and the error text associated with it.

The Status and Error Text can both be  again can be changed by signing into the self-service hub here


going to the bottom left and using the “Manage errors” section.

You can read more on how to change it here https://documents.applyfinancial.co.uk/self-service-hub-introduction/changing-errors-status-and-text.

The error text can be changed in the self-service hub and this text which you have personalised can be retrieved by adding the errorComment and setting it to E field to your request.  This will mean that you don’t have to use development time to create mapping tbales for the errors.


If you submit a reference this is where it will be returned to you, if you did not submit a reference then we will complete it with our own unique reference for you and return it in this field.

“ref”: “20170711170316996”,

Bank Details

The rest of the response is 3 sections branch, head office and payment branch details.  What you use from this depends on what you require for you systems/compliance and business processes.

This consists of the bank address details and its codes, followed by

SEPA Status

This tells you the SEPA status for

Sepa credit transfers

SEPA direct debits

SEPA B2B direct debits

SEPA Instant credit transfers

The final field SEPA ICT request you to have the field sepaAll set to Y in the request to return this field

3. Add the account number

You can take the branch that the client selected and add the account number.  We will then be able to perform additional validation against the details they have.

4. Which additional details and validations are available

The final section tells you if we have additional information for the branch which can be retrieved at no additional code using the final field bankToken.  IF you use that token within 10 minutes using that in conjunction with the freeToken at the bottom of the response you will be able to retrieve the information detailed below.

These flags tell you what additional information is available

“additionalData”: {
“ssiAvailable”: “Y”,
“payServiceAvailable”: “Y”,
“contactsAvailable”: “Y”,
“messageAvailable”: “N”,
“holidayAvailable”: “Y”


4. Additional validations

Here is some more details on the additional validations that are available

SSIs Available  

Are SSIs available in a currency for this branch


This indicates if we have information on the domestic payment network for example in the UK BACS, CHAPS, faster payments, etc, this can be retrieved using call 2.1. More information is held here



Contacts Available          

This indicates if we publish contact details for the bank so you can call them if you need to get information on a payment.

More information is held here



Message Available   

This indicates if payment reason codes are available. More information is held here



Holiday Available  

This indicates if holiday details are available


Other elements which are available in calls


Complete Message Details Validation

This will validate the entire set of fields described in the data cleansing and the payment validation calls below

Data Cleansing and FATF

This will validate the Debtor and Creditor address, name fields and the payment reference field for character validity and that the name is a well-constructed and full name.

Payment Validation, SEPA and charging

This will validate the payment details and give back information on the validity of the data the bank branches and the payment charge types.

Holiday T+

The holiday call will return the holiday between the sender and receiver for the next 7 days and give you a possible delay time.  IF you set your standard T+ date then we will tell you when the t+ date is likely to be so you can warn users of any possible payment delay.

Local Language

We’re return the bank details in the local language