BIC / SWIFT Code Validation API



How to integrate BIC Validation API in your software


1. What is the BIC Validation API?


When processing wire payments and dealing with IBAN related transactions, providing the correct SWIFT / BIC code is vital to succecssful payments.
Our company has licensed the official BIC Directory from S.W.I.F.T SCRL to provide a powerful and simple way of validating BIC automatically. This service allows you to integrate BIC code directory lookup in your software for internal purposes

BIC Validation API has SWIFTRef Data Inside. BIC data used with permission of S.W.I.F.T. SCRL. Database rights reserved 2017




2. Features


BIC Validation API key features:




3. API Usage


The BIC Validation API is REST based and supports simple HTTP GET or POST requests.

The accepted parameters are listed in the table below:

Field Name Length Type Description
bic 11 String BIC / SWIFT code to lookup. Can be 8 or 11 characters
bank_name 256 String Part of a bank name to perform search in the BIC direcotry.
country 2 String Two letter country code. Required when searching by bank name.
api_key 128 String Your personal API key.
format 4 String Required to specify the format of the returned data. Currently supported values: json, xml
limit Integer Optional: can be used to limit the number of results when searching by bank name.
hist integer Optional: can be used to display historical records from the database for both bank and BIC search.
Inside your Online Portal you can find your API key and Request Endpoint URL, which is used to secure the search requests.





4. API XML Response Structure


You can download an XSD Schema of the API response.
A detailed description of the fields returned can be seen in the table below:

Field name Type Length Always present Description
MODIFICATION FLAG Alphabetic 1 Yes In delta files:
• A (addition)
• M (modification)
• D (deletion) in full files In full files:
• A (addition)
CHANGED FIELD Numeric 186 No Records the field (or TAG) that has changed either as a result of a modification to a record or as the result of a new EVENT.
One or more columns are indicated as a sequence of numbers with each number representing the column changed from the previous record instance or previous EVENT.
Example "6,7,8,9"
This means that EVENT TYPE, EVENT DATE, BIC8, and BRANCH BIC have
changed.
The following FIELDS are excluded from being recorded in CHANGED FIELD:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Alphanumeric 12 Yes The unique key of the record in the file
Each record represents an event in the BIC life-cycle.
Once assigned, the RECORD KEY never changes.
PREVIOUS RECORD KEY Alphanumeric 12 No The RECORD KEY of the previously linked EVENT
All related events are linked and can be located using this information.
NEXT RECORD KEY Alphanumeric 12 No The RECORD KEY of the next related linked event
All related events are linked and can be located using this information
EVENT TYPE Alphabetic 32 Yes The EVENT or change description related to the BIC that has occurred in the past, in the present, or will occur in the future.
Event Types:
• BIC ISSUED
• BIC EXPIRED
• BIC ACTIVATED ON FIN
• BIC ACTIVATED ON FA
• BIC ACTIVATED ON IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DEACTIVATED ON IA
• BIC DEACTIVATED
• BIC SUSPENDED
• BIC REACTIVATED
• BIC PUBLISHED
• BIC LEGAL NAME CHANGED
• BIC INSTITUTION NAME CHANGED
• BIC ADDRESS CHANGED
• FIN SERVICE CODE CHANGED
The last update date is the last line of the BIC sequence (that is, the most recent entry).
When a new EVENT is added, the MODIFICATION FLAG and CHANGED
FIELD column will be updated in the immediate previous related EVENT.
EVENT DATE Alphanumeric 8 Yes The date of the EVENT
BIC8 Alphanumeric 8 Yes BIC (institution, country, and party suffix) where:
• Party prefix (4 char)
• Country code (2 char)
• Party suffix (2 char)
BRANCH BIC Alphanumeric 3 Yes The BIC branch identifier associated with the 8-character BIC. If no branch identifier exists, then XXX is used.
BIC Alphanumeric 11 Yes The full BIC: 8-character BIC and branch identifier
RECORD STATUS Alphabetic 1 Yes Indicates the status of the record:
• [C] = Current representing the latest event in the chain up until the date of publication, excluding [F]uture events
• [H] = Historical records in the event chain
• [F] = Future event that will occur after the publication date of the directory. The previously indicated [C]urrent event will be valid up until the date specified in the [F]uture event.
For FUTURE events, the date indicates when the change will be VALID FROM.
OPERATIONALLY ACTIVE RECORD Alpha 1 Yes There are multiple records for the same BIC. This field indicates which of the records for the same BIC is the operationally active BIC and should be used.
• [Y] Operationally active
• [N] Operationally inactive
For each unique BIC, there is a single record entry indicating an ACTIVE status (Y).
Records with [H]istorical status will always indicate [N].
Records with [C]urrent may indicate [Y] or [N].
Records with [F] will always indicate [N].
SUBTYPE INDICATOR Any type 4 Yes The business type of the entity. Subtype Indicator is provided only for records with a BIC.
SWIFT FIN Alphabetic 1 Yes Status of an entity's connection to FIN:
• [Y] connected to FIN
• [N] not connected to FIN
SWIFT FA Alphabetic 1 Yes Status of an entity's reachability through FileAct:
• [Y] connected to FileAct
• [N] not connected to FileAct
SWIFT IA Alpha 1 Yes Status of an entity's reachability through InterAct:
• [Y] connected to InterAct
• [N] not connected to InterAct
LEGAL NAME Any 105 No Institution legal name
INSTITUTION NAME Any 105 Yes Institution trading name (published name)
INSTITUTION TYPE Alphabetic 12 Yes Organisation that is principally engaged in financial intermediation and/or in auxiliary financial activities
Institution type:
• FINANCIAL
• NONFINANCIAL
ENTITY TYPE Alphabetic 16 Yes Identifies the type of financial entity:
• Legal Entity
• Branch
• Operational
RE STREET ADDRESS 1 Any 35 No [Registration] Street name
RE STREET ADDRESS 2 Any 35 No [Registration] Street number
RE STREET ADDRESS 3 Any 35 No [Registration] Building, building name, floor
RE STREET ADDRESS 4 Any 35 No [Registration] Area
RE CITY Any 35 No [Registration] City name of the institution/branch
RE CPS Any 90 No [Registration] County, province, state, or other administrative region of the owner institution/branch
RE ZIP CODE Any 15 No [Registration] Zip code of the institution/ branch
RE POB NUMBER Any 35 No Comma-separated field with the POB number of the institution/branch and the related ZIP code.
Example
"POB 103352, 40024"
This allows customers to use the full POB address:
POB 103352
40024, DUESSELDORF (CITY)
OP STREET ADDRESS 1 Any 35 No [Operational] Street name
OP STREET ADDRESS 2 Any 35 No [Operational] Street number
OP STREET ADDRESS 3 Any 35 No [Operational] Building, building name, floor
OP STREET ADDRESS 4 Any 35 No [Operational] Area
OP CITY Any 35 No [Operational] City name of the institution/branch
OP CPS Any 90 No [Operational] County, province, state, or other administrative region of the owner institution/branch
OP ZIP CODE Any 15 No [Operational] Zip code of the institution/ branch
OP POB NUMBER Any 35 No Comma-separated field with the POB number of the institution/branch and the related ZIP code.
Example
"POB 103352, 40024"
This allows customers to use the full POB address:
POB 103352
40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 Any 35 No [Branch] Street name
BR STREET ADDRESS 2 Any 35 No [Branch] Street number
BR STREET ADDRESS 3 Any 35 No [Branch] Building, building name, floor
BR STREET ADDRESS 4 Any 35 No [Branch] Area
BR CITY Any 35 No [Branch] City name of the institution/ branch
BR CPS Any 90 No [Branch] County, province, state, or other administrative region of the owner institution/branch
BR ZIP CODE Any 15 No [Branch] Zip code of the institution/ branch
BR POB NUMBER Any 35 No Comma-separated field with the POB number of the institution/branch and the related ZIP code.
Example
"POB 103352, 40024"
This allows customers to use the full POB address:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION Any 70 No Branch information
This is a free text description of the branch as provided by the financial institution to which it belongs. For the time being this will be provided only for entries with a BIC and only when the financial institution concerned wants to provide this extra information. The information is sourced from the BIC Directory.
COUNTRY NAME Any 70 Yes The country name of the institution/ branch as indicated in the ISO 3166
ISO COUNTRY CODE Alphabetic 2 Yes The ISO 3166-1 alpha-2 code of the country of the institution/branch
LOCATION CODE Any type 1 Yes Contains the location (formally in position 7 of BIC standard:2009)
Examples:
• In FR, BICs in Paris = P
• In BE, BICs in Brussels = B
• In US, BICs in East Cost = 3
FIN SERVICE CODES Any type 60 No FIN service codes (also called value- added service codes). Service Codes are provided only for records containing a BIC.
The field can contain up to 20 three- character codes in alphabetical order.
RECORD KEY BDP Alphanumeric 12 No The unique key of the Bank Directory Plus record in the file.
FIELD A Any 1 No Reserved for future use
FIELD B Any 64 No Reserved for future use
FIELD C Any 128 No Reserved for future use
FIELD D Any 256 No Reserved for future use
FIELD E Any 11 No Reserved for future use
FIELD F Any 12 No Reserved for future use
The API system returns results in XML format, which is easy to parse in a variety of programming languages and platforms.

A sample XML reply from the API for a BIC search would be:


<result>
<bicdata>
<row>
<modification_flag>A</modification_flag>
<changed_field>34</changed_field>
<record_key>BP0000004OQQ</record_key>
<previous_record_key>BP00000030XZ</previous_record_key>
<next_record_key/>
<event_type>BIC ADDRESS CHANGED</event_type>
<event_date>20150606</event_date>
<bic8>BARCGB22</bic8>
<branch_bic>XXX</branch_bic>
<bic>BARCGB22XXX</bic>
<record_status>C</record_status>
<operationally_active_record>Y</operationally_active_record>
<subtype_indicator>SUPE</subtype_indicator>
<swift_fin>Y</swift_fin>
<swift_fa>N</swift_fa>
<swift_ia>N</swift_ia>
<legal_name>BARCLAYS BANK PLC</legal_name>
<institution_name>BARCLAYS BANK PLC</institution_name>
<institution_type>FINANCIAL</institution_type>
<entity_type>Legal Entity</entity_type>
<re_street_address_1>1, CHURCHILL PLACE</re_street_address_1>
<re_street_address_2/>
<re_street_address_3/>
<re_street_address_4/>
<re_city>LONDON</re_city>
<re_cps/>
<re_zip_code>E14 5HP</re_zip_code>
<re_pob_number/>
<op_street_address_1>1 CHURCHILL PLACE</op_street_address_1>
<op_street_address_2/>
<op_street_address_3/>
<op_street_address_4/>
<op_city>LONDON</op_city>
<op_cps>LONDON E14 5HP</op_cps>
<op_zip_code/>
<op_pob_number/>
<br_street_address_1/>
<br_street_address_2/>
<br_street_address_3/>
<br_street_address_4/>
<br_city/>
<br_cps/>
<br_zip_code/>
<br_pob_number/>
<branch_information>(ALL U.K. OFFICES)</branch_information>
<country_name>UNITED KINGDOM</country_name>
<iso_country_code>GB</iso_country_code>
<location_code>2</location_code>
<fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes>
<record_key_bdp>BD00000006FO</record_key_bdp>
<field_a/>
<field_b/>
<field_c/>
<field_d/>
<field_e/>
<field_f></field_f>
</row>
</bicdata>
<errors/>
</result>





5. API Errors


In case of an error the API returns an XML response containing the error message.

The XML tags are returned without any other fields in the XML response.

Below you can find a description of all possible error messages that could be returned:

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
401 Input Error Accepted SWIFT length 8 or 11 characters'
402 Input Error Bank Name Invalid! Bank search should be minimum of 4 characters.
Allowed characters a-z, A-Z, 0-9, [space]!
403 Input Error Country code incorrect! Allowed is 2 letter country code. Example: UK, DE, FR