> ## 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-Validierung

> Der `iban`-Endpunkt validiert International Bank Account Numbers mit umfassender länderspezifischer Prüfung, Formatkontrolle und detaillierten Strukturinformationen für Finanzanwendungen.

## Erste Schritte

### Basis-URL

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

### Validierungs-Endpunkt

Der `iban`-Endpunkt benötigt Ihren API-Schlüssel und einen IBAN-Parameter zur umfassenden Validierung von International Bank Account Numbers.

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

Diese erfolgreiche Anfrage validiert eine deutsche IBAN und liefert detaillierte Informationen:

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

### Anfrageparameter

<ParamField query="api_key" type="String" required>
  Ihr eindeutiger API-Schlüssel. Beachten Sie, dass jeder Nutzer für *jede*
  Cleariflow-API eigene API-Schlüssel hat — Ihr Bankvalidierungs-API-Schlüssel funktioniert z. B. nicht für die Wechselkurs-API.
</ParamField>

<ParamField query="iban" type="String" required>
  Die zu validierende International Bank Account Number. Leerzeichen sind erlaubt und werden bei der Verarbeitung automatisch entfernt. Die IBAN sollte dem ISO-13616-Standardformat entsprechen.
</ParamField>

### Antwortparameter

Die API-Antwort wird in einem universellen und leichtgewichtigen [JSON-Format](https://www.json.org/json-en.html) zurückgegeben.

<ResponseField name="iban" type="String">
  Die normalisierte IBAN ohne Leerzeichen, in Großbuchstaben.
</ResponseField>

<ResponseField name="is_valid" type="Boolean">
  Gesamtergebnis der Validierung — ob die IBAN allen Validierungsregeln entspricht.
</ResponseField>

<ResponseField name="country_code" type="String">
  Der zweistellige ISO-Ländercode (z. B. DE für Deutschland, FR für Frankreich).
</ResponseField>

<ResponseField name="country_name" type="String">
  Der vollständige Name des Landes, dem die IBAN zugeordnet ist.
</ResponseField>

<ResponseField name="bank_code" type="String">
  Der aus der IBAN extrahierte Bankidentifikationscode gemäß dem länderspezifischen Format.
</ResponseField>

<ResponseField name="account_number" type="String">
  Der Kontonummernteil der IBAN ohne Ländercode, Prüfziffern und Bankcode.
</ResponseField>

<ResponseField name="length" type="Integer">
  Die tatsächliche Länge der übermittelten IBAN.
</ResponseField>

<ResponseField name="expected_length" type="Integer">
  Die erwartete Länge für IBANs des jeweiligen Landes gemäß ISO 13616.
</ResponseField>

<ResponseField name="checksum_valid" type="Boolean">
  Ob die IBAN-Prüfziffernvalidierung mit dem MOD-97-Algorithmus bestanden wurde.
</ResponseField>

<ResponseField name="format_valid" type="Boolean">
  Ob das IBAN-Format der erwarteten Struktur des Landes entspricht.
</ResponseField>

<ResponseField name="details" type="Object">
  Zusätzliche Detailinformationen zur IBAN-Struktur und Formatierung.
</ResponseField>

<ResponseField name="details.structure" type="String">
  Visuelle Darstellung der IBAN-Struktur mit Platzhaltern B (Bank), S (Sort), C (Customer) und K (Key).
</ResponseField>

<ResponseField name="details.example" type="String">
  Ein korrekt formatiertes IBAN-Beispiel mit Leerzeichen zur besseren Lesbarkeit.
</ResponseField>

<ResponseField name="details.bank_name" type="String">
  Der Name der Bank (derzeit „Bank information not available").
</ResponseField>

<ResponseField name="details.bank_bic" type="String">
  Der BIC-Code der Bank (derzeit „BIC not available").
</ResponseField>

<ResponseField name="details.account_type" type="String">
  Der Kontotyp (typischerweise „Bank Account").
</ResponseField>

<ResponseField name="details.currency" type="String">
  Der Währungscode des Landes (z. B. EUR für Eurozone-Länder, GBP für UK).
</ResponseField>

## Beispiele

### Gültige deutsche IBAN

**Anfrage:**

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

**Antwort:**

```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"
  }
}
```

### Gültige französische IBAN

**Anfrage:**

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

**Antwort:**

```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"
  }
}
```

### Ungültige IBAN

**Anfrage:**

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

**Antwort:**

```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": ""
  }
}
```

## Fehlerbehandlung

### Fehlender IBAN-Parameter

**Anfrage:**

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

**Antwort:**

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

### Fehlender API-Schlüssel

**Anfrage:**

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

**Antwort:**

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

## IBAN-Struktur

Die IBAN besteht aus mehreren Komponenten:

1. **Ländercode (2 Zeichen)**: ISO-3166-1-alpha-2-Ländercode
2. **Prüfziffern (2 Zeichen)**: MOD-97-Algorithmus-Validierung
3. **Bankidentifikator**: Länderspezifischer Bankcode
4. **Kontonummer**: Kundenkontokennung

### Länderspezifische Formate

Verschiedene Länder haben unterschiedliche IBAN-Strukturen:

* **Deutschland (DE)**: 22 Zeichen — `BBBB BBBB BBBB BBBB BB`
* **Frankreich (FR)**: 27 Zeichen — `BBBB BSSS SSCC CCCC CCCC CCC KK`
* **Italien (IT)**: 27 Zeichen — `CAAA AABB BBSS CCCC CCCC CCX`
* **Vereinigtes Königreich (GB)**: 22 Zeichen — `BBBB SSSS SSCC CCCC CC`
* **Spanien (ES)**: 24 Zeichen — `BBBB SSSS DDCC CCCC CCCC CC`

Dabei gilt:

* **B** = Bankcode
* **S** = Sort-Code
* **C** = Kundenkontonummer
* **K** = Schlüssel-/Prüfziffer
* **A** = Kontotyp
* **D** = Kontrollziffer

## Validierungsregeln

Die API führt umfassende Validierung durch, einschließlich:

1. **Formatvalidierung**: Prüft, ob die IBAN der erwarteten Struktur des Landes entspricht
2. **Längenvalidierung**: Prüft, ob die IBAN-Länge dem Landesstandard entspricht
3. **Prüfziffernvalidierung**: Führt MOD-97-Algorithmus-Validierung durch
4. **Ländercode-Validierung**: Stellt sicher, dass der Ländercode unterstützt wird
5. **Zeichenvalidierung**: Prüft auf gültige alphanumerische Zeichen

## Unterstützte Länder

Die API unterstützt IBAN-Validierung für über 50 Länder, darunter:

* **Europa**: Deutschland, Frankreich, Italien, Spanien, Niederlande, Belgien, Österreich, Schweiz, UK, Polen
* **Asien**: VAE, Bahrain, Israel, Jordanien, Kasachstan, Kuwait
* **Amerika**: Brasilien, Costa Rica, Dominikanische Republik, Guatemala
* **Afrika**: Mauretanien, Mauritius, Tunesien

Eine vollständige Liste finden Sie auf der Seite [Unterstützte Länder](/bank-validation/countries).