EN
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 sucecssful 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 2018
2. Features
BIC Validation API key features:- Retrieve information about the bank based on the BIC.
- Search the BIC directory by a part of the bank name and country.
- Search the BIC Directory for historical records.
- Use both complete and simplified API response for easier integration.
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. |
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 |
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
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 |