> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IBAN validation

> The `iban` endpoint validates International Bank Account Numbers with comprehensive country-specific validation, format checking, and detailed structural information for financial applications.

## Getting started

### Base URL

```
https://bankvalidation.cleariflow.com/v1/iban/
```

### Validation endpoint

The `iban` endpoint requires your API key and an IBAN parameter to perform comprehensive validation of International Bank Account Numbers.

```
https://bankvalidation.cleariflow.com/v1/iban/
? api_key = YOUR_UNIQUE_API_KEY
& iban = DE89370400440532013000
```

This successful request validates a German IBAN and returns detailed information:

<ResponseExample>
  ```json theme={"system"}
  {
    "iban": "DE89370400440532013000",
    "is_valid": true,
    "country_code": "DE",
    "country_name": "Germany",
    "bank_code": "37040044",
    "account_number": "0532013000",
    "length": 22,
    "expected_length": 22,
    "checksum_valid": true,
    "format_valid": true,
    "details": {
      "structure": "BBBB BBBB BBBB BBBB BB",
      "example": "DE89 3704 0044 0532 0130 00",
      "bank_name": "Bank information not available",
      "bank_bic": "BIC not available",
      "account_type": "Bank Account",
      "currency": "EUR"
    }
  }
  ```
</ResponseExample>

### Request parameters

<ParamField query="api_key" type="String" required>
  Your unique API key. Note that each user has unique API keys *for each of
  Cleariflow APIs*, so your Bank Validation API key will not work for your Exchange
  Rates API, for example.
</ParamField>

<ParamField query="iban" type="String" required>
  The International Bank Account Number to validate. Spaces are allowed and will be automatically removed during processing. The IBAN should follow the ISO 13616 standard format.
</ParamField>

### Response parameters

The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html).

<ResponseField name="iban" type="String">
  The normalized IBAN without spaces, returned in uppercase format.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Overall validation result indicating whether the IBAN is valid according to all validation rules.
</ResponseField>

<ResponseField name="country_code" type="String">
  The two-letter ISO country code (e.g., DE for Germany, FR for France).
</ResponseField>

<ResponseField name="country_name" type="String">
  The full name of the country associated with the IBAN.
</ResponseField>

<ResponseField name="bank_code" type="String">
  The bank identifier code extracted from the IBAN according to the country's specific format.
</ResponseField>

<ResponseField name="account_number" type="String">
  The account number portion of the IBAN, excluding country code, checksum, and bank code.
</ResponseField>

<ResponseField name="length" type="Integer">
  The actual length of the provided IBAN.
</ResponseField>

<ResponseField name="expected_length" type="Integer">
  The expected length for IBANs from the specific country according to ISO 13616 standard.
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  Whether the IBAN checksum validation passed using the MOD-97 algorithm.
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  Whether the IBAN format matches the expected structure for the country.
</ResponseField>

<ResponseField name="details" type="Object">
  Additional detailed information about the IBAN structure and formatting.
</ResponseField>

<ResponseField name="details.structure" type="String">
  A visual representation of the IBAN structure using B (Bank), S (Sort), C (Customer), and K (Key) placeholders.
</ResponseField>

<ResponseField name="details.example" type="String">
  A properly formatted example of the IBAN with spaces for readability.
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  The name of the bank (currently shows "Bank information not available").
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  The BIC code for the bank (currently shows "BIC not available").
</ResponseField>

<ResponseField name="details.account_type" type="String">
  The type of account (typically "Bank Account").
</ResponseField>

<ResponseField name="details.currency" type="String">
  The currency code for the country (e.g., EUR for Eurozone countries, GBP for UK).
</ResponseField>

## Examples

### Valid German IBAN

**Request:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=DE89370400440532013000
```

**Response:**

```json theme={"system"}
{
  "iban": "DE89370400440532013000",
  "is_valid": true,
  "country_code": "DE",
  "country_name": "Germany",
  "bank_code": "37040044",
  "account_number": "0532013000",
  "length": 22,
  "expected_length": 22,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BBBB BBBB BBBB BB",
    "example": "DE89 3704 0044 0532 0130 00",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}
```

### Valid French IBAN

**Request:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=FR1420041010050500013M02606
```

**Response:**

```json theme={"system"}
{
  "iban": "FR1420041010050500013M02606",
  "is_valid": true,
  "country_code": "FR",
  "country_name": "France",
  "bank_code": "2004101005",
  "account_number": "0500013M02606",
  "length": 27,
  "expected_length": 27,
  "checksum_valid": true,
  "format_valid": true,
  "details": {
    "structure": "BBBB BSSS SSCC CCCC CCCC CCC KK",
    "example": "FR14 2004 1010 0505 0001 3M02 606",
    "bank_name": "Bank information not available",
    "bank_bic": "BIC not available",
    "account_type": "Bank Account",
    "currency": "EUR"
  }
}
```

### Invalid IBAN

**Request:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=INVALID
```

**Response:**

```json theme={"system"}
{
  "iban": "",
  "is_valid": false,
  "country_code": "",
  "country_name": "",
  "bank_code": "",
  "account_number": "",
  "length": 7,
  "expected_length": 0,
  "checksum_valid": false,
  "format_valid": false,
  "details": {
    "structure": "",
    "example": ""
  }
}
```

## Error handling

### Missing IBAN parameter

**Request:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY
```

**Response:**

```json theme={"system"}
{
  "error": {
    "message": "Missing iban",
    "code": "missing_iban"
  }
}
```

### Missing API key

**Request:**

```
GET https://bankvalidation.cleariflow.com/v1/iban/?iban=DE89370400440532013000
```

**Response:**

```json theme={"system"}
{
  "error": {
    "message": "API key is required",
    "code": "missing_api_key"
  }
}
```

## IBAN Structure

The IBAN consists of several components:

1. **Country Code (2 characters)**: ISO 3166-1 alpha-2 country code
2. **Check Digits (2 characters)**: MOD-97 algorithm validation
3. **Bank Identifier**: Country-specific bank code
4. **Account Number**: Customer account identifier

### Country-specific formats

Different countries have varying IBAN structures:

* **Germany (DE)**: 22 characters - `BBBB BBBB BBBB BBBB BB`
* **France (FR)**: 27 characters - `BBBB BSSS SSCC CCCC CCCC CCC KK`
* **Italy (IT)**: 27 characters - `CAAA AABB BBSS CCCC CCCC CCX`
* **United Kingdom (GB)**: 22 characters - `BBBB SSSS SSCC CCCC CC`
* **Spain (ES)**: 24 characters - `BBBB SSSS DDCC CCCC CCCC CC`

Where:

* **B** = Bank code
* **S** = Sort code
* **C** = Customer account number
* **K** = Key/Check digit
* **A** = Account type
* **D** = Control digit

## Validation Rules

The API performs comprehensive validation including:

1. **Format Validation**: Checks if the IBAN follows the expected structure for the country
2. **Length Validation**: Verifies the IBAN length matches the country standard
3. **Checksum Validation**: Performs MOD-97 algorithm validation
4. **Country Code Validation**: Ensures the country code is supported
5. **Character Validation**: Checks for valid alphanumeric characters

## Supported Countries

The API supports IBAN validation for 50+ countries including:

* **Europe**: Germany, France, Italy, Spain, Netherlands, Belgium, Austria, Switzerland, UK, Poland
* **Asia**: UAE, Bahrain, Israel, Jordan, Kazakhstan, Kuwait
* **Americas**: Brazil, Costa Rica, Dominican Republic, Guatemala
* **Africa**: Mauritania, Mauritius, Tunisia

For a complete list of supported countries, see the [Supported Countries](/bank-validation/countries) page.