Bankers Almanac® Validate API Portal
© 2023 LexisNexis Risk Solutions Group

Finding correspondents

Home Validate API Correspondents Finding correspondents
by

This call is designed to return the correspondent bank details required to make a payment.  The call will validate the clients account number and bank code data and respond with the bank details and the correspondent details for the currency that the user entered.  The search criteria as below and also require the user to enter a valid ISO currency code.

  1. National id
  2. BIC
  3. National id and domestic account number
  4. BIC and domestic account number
  5. Structured account number (BBAN, IBAN or CLABE).

The service returns a recommended account number and national id and BIC and any correspondents for the chosen currency.  The service will also return the details for the Branch and additional branch (these may be the same branch) and can be specified in the request parameters.

The details in the response for each of the 2 branches include:

  1. Name
  2. Address
  3. Domestic and International Codes
  4. SEPA Status
  5. Correspondent details
  6. Indicators of other currencies that the bank transacts in

METHOD

GET command, in “application/json” format

ENDPOINT

https://validate.bankersalmanac.com/validate-api/rest/convert/2.0.1

REQUEST

The request parameters can be downloaded here

Field Name Field description Type
currencyCode ISO 3 digit currency code xs:string
countryCode ISO 2 digit country code xs:string
nationalId Domestic bank code or SWIFT BIC xs:string
accountNumber Domestic bank account number or IBAN xs:string
dataStore Unused xs:string
ref Your transaction reference xs:string
group Unused xs:string
bic8 Do you want BIC8 returned for head offices
Y = 8 digit BIC returned for head office BICs
N = 11 digit BIC always returned		 xs:string
token Security token xs:string
freeToken If you have perfomed a valdiation and wish to retrieve the correspndents then enter the freeToken here to retrieve additional details at no additional cost.  The only other required details are the bankToken to identify the branch and the currency code xs:string
bankToken If you have perfomed a valdiation and wish to retrieve the correspndents then enter the bankToken here to retrieve additional details at no additional cost.  The only other required details are the bankToken to identify the branch and the currency code xs:string
requestBranch The requestBranch parameter, this would allow us to put in a letter to specify the branch.

H – Head office
F – first branch retrieved

 xs:string
errorComment Error codes xs:string

 and here is the extract from the service WADL

<resource path=”/2.0.1“>
<method name=”GET“>
<request>
<param name=”currencyCode“ style=”query“ type=”xs:string“/>
<param name=”countryCode“ style=”query“ type=”xs:string“/>
<param name=”nationalId“ style=”query“ type=”xs:string“/>
<param name=”accountNumber“ style=”query“ type=”xs:string“/>
<param name=”dataStore“ style=”query“ type=”xs:string“/>
<param name=”ref“ style=”query“ type=”xs:string“/>
<param name=”group“ style=”query“ type=”xs:string“/>
<param name=”bic8“ style=”query“ type=”xs:string“/>
<param name=”token“ style=”query“ type=”xs:string“/>
<param name=”freeToken“ style=”query“ type=”xs:string“/>
<param name=”bankToken“ style=”query“ type=”xs:string“/>
<param name=”requestBranch” style=”query“ type=”xs:string“/>
<param name=”errorComment“ style=”query“ type=”xs:string“/>
</request>

RESPONSE

The response sample is below

Field name Description Format Type Example
countryCode ISO Country Code Alpha String GB
currencyCode ISO currency code Alpha String USD
nationalId Domestic National ID Alphanumeric String 309408
accountNumber Domestic Account Number, BBAN or IBAN Alphanumeric String 1638696
status Status of the call (e.g. pass, caution or fail) Alpha String PASS
comment Alphanumeric & Extended Characters String
recommendedNatId Recommended change to the entered national id Alphanumeric String 309408
recommendedAcct Recommended change to the entered account number Alphanumeric String 1638696
recommendedBIC Recommended change to the entered BIC Alphanumeric String LOYDGB21124
ref Record reference Alphanumeric String 8jgtMNYQTNkoRPd5q6IB
group Used to group stored record – currently not in use Alphanumeric String null
branchDetails Field Label String
bankName Banks Name Alphanumeric String LLOYDS BANK PLC,
branch Branch Name Alphanumeric String (HEMEL HEMPSTEAD MARLOWES -309408),
street Street Name Alphanumeric String 198-200 MARLOWES,
city City name Alphanumeric String HEMEL HEMPSTEAD,
postZip Postal or Zip code Alphanumeric String HP1 1BH,
region Alphanumeric String null,
country ISO Country Name Alphanumeric String UNITED KINGDOM,
codeName1 Code set 1 name Alphanumeric String BIC,
codeValue1 Code set 1 value Alphanumeric String LOYDGB21124,
codeName2 Code set 2 name Alphanumeric String CHIPS,
codeValue2 Code set 2 value Alphanumeric String null,
codeName3 Code set 3 name Alphanumeric String BIC-4,
codeValue3 Code set 3 value Alphanumeric String LOYD,
codeName4 Code set 4 name Alphanumeric String Sort Code,
codeValue4 Code set 4 value Alphanumeric String 309408
sepaDetails Field Label String
ctStatus SEPA Credit Transfer Compliance Status Alpha String YES
ddStatus SEPA Direct Debit Core Compliance Status Alpha String YES
bbStatus SEPA Direct Debit B2B Compliance Status Alpha String YES
additionalData String
ssiDetails Field Label
assetCategory Asset category of the payment ALL, COMMERCAIL, FINANCIAL COMMERCIAL
corresBIC BIC of the correspondent IRVTUS3NXXX
bankName Name of correspondent banks THE BANK OF NEW YORK MELLON
corresAcct Account number of the correspondent account
intrmyBIC1 BIC of the correspondents intermediary bank
intrmyAcct1 Account number of the correspondent intermediary bank
intrmyBIC2 BIC of the correspondents intermediary bank
intrmyAcct2 Account number of the correspondent account intermediary bank
availableCurrencies ISO currency code of the available correspondents Alpha String AED,AUD,BBD,BHD,CAD,CHF,CNY,CZK
contactsAvailable Contact details available Alpha String N
messageAvailable Payment message requirements are available for example payment purpose codes Alpha String Y
bankToken This token allows you to get the bank and branch details for this branch using call 1.3 free of charge, in conjunction with the freeToken Alphanumeric String NHvoOgC6r8LUDxWCuSbPwIJ3ED03zBg2UNZEH9aWHhCNtLHf8E2aDAieth
bankName Banks Name Alphanumeric String LLOYDS BANK PLC,
branch Branch Name Alphanumeric String (HEMEL HEMPSTEAD MARLOWES -309408),
street Street Name Alphanumeric String 198-200 MARLOWES,
city City name Alphanumeric String HEMEL HEMPSTEAD,
postZip Postal code Alphanumeric String HP1 1BH,
region Alphanumeric String null,
country ISO Country Name Alphanumeric String UNITED KINGDOM,
codeName1 Code set 1 name Alphanumeric String BIC,
codeValue1 Code set 1 value Alphanumeric String LOYDGB21124,
codeName2 Code set 2 name Alphanumeric String CHIPS,
codeValue2 Code set 2 value Alphanumeric String null,
codeName3 Code set 3 name Alphanumeric String BIC-4,
codeValue3 Code set 3 value Alphanumeric String LOYD,
codeName4 Code set 4 name Alphanumeric String Sort Code,
codeValue4 Code set 4 value Alphanumeric String 309408
contactsAvailable Contact details available Alpha String N,
freeToken This token allows you to use the contacts and pay service calls free to retrieve these details for a branch for a limited time Alphanumeric String F65tRepPbSadCqnQ04HIzJpsqI3ahHyR0eHlInnjipyrIDHSVQUoBaZ9Qieie

TEST

Try testing using POSTMAN which is available as a Google Chrome App and can be found here POSTMAN REST Client we have saved a project which you can download and use here POSTMAN Call.  Just enter a valid authentication token and you’re working.  The test data entered into this sample is

Country Code: GB
National Code: 309408
Account Number: 01638696
Currency Code: USD