API integration specification
1. What does the IBAN Recovery API do?
This API provides the unique functionality to recover up to two unknown characters from any International Bank Account Number. This function can be used in cases where parts of the IBAN are unreadable or when user input is validated. The system takes into account the specific country formatting and length to ensure it produces the minimum amount of suggestions. All possible permutations of digits and letters according to the international formatting scheme are tested against the modulust check digit algorithm.
- Unreadable Characters - When digitizing IBANs from paper carriers it is possible for degraded print to produce unreadable characters. Our system allows you to place a question mark "?" in place of the unknown characters. Our validation engine then generates all possible valid combinations for this IBAN.
- Educated Guess - If you have an invalid IBAN, you can make educated guess at which positions the error may be by running multiple recovery attempts with wildcard "?" markers at different positions.
The IBAN Recovery API allows you to do the following:
- Get a list of valid IBANs which suggest the possible correct variant.
- Extract the domestic bank code from the original IBAN submitted.
- Extract the domestic branch code from the original IBAN submitted.
- Extract the domestic account number from the original IBAN submitted.
3. Recovery API Requests
The API system allows you to automate IBAN recovery via a simple HTTP GET or POST request.
The accepted parameters are listed in the table below:
|IBAN||Max 100||String||The masked IBAN you want to validate. Use "?" (question mark) in place of the unknown character. For example: DE79850?0300310018056?|
|api_key||128||String||Your personal API key.|
|format||5||String||Format of the response XML and JSON supported.|
*To obtain an API key, please contact us at firstname.lastname@example.org or purchase a subscription at our order page
EXAMPLE – Recover an IBAN
An example usage of the IBAN Validation API with a GET request can be found below:
- key is your API key
- IBAN sent for validation by the API module. Example: CH8?0853410203475000?
- xml is the response format. Also a json keyword can be specified for json formatted response.
Once an HTTP GET or POST request is made with the correct API key, the system will return the results in the specified format. You can find an sample response in the next section “API Response Structure”
4. Recovery API Response
An XSD Schema of the API’s response can be found below:
A detailed description of the format_data object fields returned can be seen in the table below:
|country||Max 2||String||The 2 letter ISO Country code.|
|iban_length||Max 2||Integer||The exact length of all IBANs for this Country.|
|format_template||Max 2||String||A template with the exact length of the IBAN showing the different characters inside per positions. C = Mixed ( Alphabet + 0-9 ), A = Character(alphabetic), N = Digit ( 0-9 ).|
|bank_code||Max 99||String||The domestic bank identifier code for this IBAN.|
|branch_code||Max 99||String||The domestic branch identifier for this IBAN.||account_number||Max 99||String||The domestic bank account number for this IBAN.|
A sample XML reply from the API for a IBAN validation query would be:
CH 21 CCNNNNNNNCCCCCCCCCCCC 85341 0203475000 CH810853410203475000K CH860853410203475000R CH8908534102034750002
5. Recovery API Status Codes
The IBAN recovery API returns the following error codes.
|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||Required fields missing.|
|402||Input Error||Too many wildcards. Maximum of two wildcards allowed.|
|403||Input Error||Too few wildcards. A minimum of one wildcards is required.|