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:




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://www.iban.com/clients/api/recover-iban.php?api_key=key&format=xml&iban=IBAN

Where:

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



	
		CH
		21
		CCNNNNNNNCCCCCCCCCCCC
		85341
		
		0203475000
	
	
		CH810853410203475000K
		CH860853410203475000R
		CH8908534102034750002
	
	






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.