IBAN Character Recovery API Documentation

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.
Use cases:

- 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.

2. Features

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:

Field Name	Length	Type	Description
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 contact@iban.com 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:

https://api.iban.com/clients/api/recover-iban.php?api_key=key&format=xml&iban=IBAN

Where:

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:

<xs:schema attributeformdefault="unqualified" elementformdefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="result">
    <xs:complextype>
      <xs:sequence>
        <xs:element name="format_data">
          <xs:complextype>
            <xs:sequence>
              <xs:element type="xs:string" name="country">
              <xs:element type="xs:byte" name="iban_length">
              <xs:element type="xs:string" name="format_template">
              <xs:element type="xs:int" name="bank_code">
              <xs:element type="xs:string" name="branch_code">
              <xs:element type="xs:int" name="account_number">
            </xs:element></xs:element></xs:element></xs:element></xs:element></xs:element></xs:sequence>
          </xs:complextype>
        </xs:element>
        <xs:element name="suggestions">
          <xs:complextype>
            <xs:sequence>
              <xs:element type="xs:string" name="iban" maxoccurs="unbounded" minoccurs="0">
            </xs:element></xs:sequence>
          </xs:complextype>
        </xs:element>
        <xs:element type="xs:string" name="errors">
      </xs:element></xs:sequence>
    </xs:complextype>
  </xs:element>
</xs:schema>

A detailed description of the format_data object fields returned can be seen in the table below:

Field Name	Length	Type	Description
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:

<result>
    <format_data>
        <country>CH</country>
        <iban_length>21</iban_length>
        <format_template>CCNNNNNNNCCCCCCCCCCCC</format_template>
        <bank_code>85341</bank_code>
        <branch_code>
        <account_number>0203475000</account_number>
    </branch_code></format_data>
    <suggestions>
        <iban>CH810853410203475000K</iban>
        <iban>CH860853410203475000R</iban>
        <iban>CH8908534102034750002</iban>
    </suggestions>
    <errors>
</errors></result>

5. Recovery API Status Codes

The IBAN recovery API returns the following error codes

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	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.