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

# POST /iban-validator

> Validate IBAN numbers and extract bank account metadata including country, formatted IBAN, and BBAN.

## Endpoint

```
POST https://api.bunny.build/api/v1/iban-validator
```

## Authentication

| Header         | Required | Value                    |
| -------------- | -------- | ------------------------ |
| `X-API-Key`    | Yes      | Your API key (`bun_...`) |
| `Content-Type` | Yes      | `application/json`       |

## Overview

Validate International Bank Account Numbers (IBANs) against the official format specification for all participating countries. Returns structural metadata including country, a human-readable formatted IBAN, and the Basic Bank Account Number (BBAN), so you can catch invalid entries before initiating a transfer.

## Use cases

* Pre-validate IBANs before submitting wire transfers
* Extract country and bank routing data from user-entered IBANs
* Block invalid IBAN entries in payment forms in real time
* Compliance checks for cross-border payment flows

## Details

Validates structure and check digits for all IBAN-participating countries. Note that structural validity does not guarantee the account exists; it confirms the number is correctly formed.

## Request body

| Field  | Type   | Required | Description                           |
| ------ | ------ | -------- | ------------------------------------- |
| `iban` | string | Yes      | IBAN to validate (spaces are ignored) |

### Example

```json theme={null}
{
  "iban": "DE89370400440532013000"
}
```

## Response

### 200 OK

| Field       | Type    | Description                                                                                   |
| ----------- | ------- | --------------------------------------------------------------------------------------------- |
| `iban`      | string  | Normalized IBAN (uppercased, spaces stripped)                                                 |
| `valid`     | boolean | Whether the IBAN is structurally valid                                                        |
| `formatted` | string  | IBAN grouped in blocks of four (e.g. `DE89 3704 0044 0532 0130 00`). Present only when valid. |
| `country`   | string  | ISO 3166-1 alpha-2 country code. Present only when valid.                                     |
| `bban`      | string  | Basic Bank Account Number (everything after the 4-char IBAN prefix). Present only when valid. |
| `error`     | string  | Human-readable reason for failure. Present only when invalid.                                 |

**Example (valid)**

```json theme={null}
{
  "iban": "DE89370400440532013000",
  "valid": true,
  "formatted": "DE89 3704 0044 0532 0130 00",
  "country": "DE",
  "bban": "370400440532013000"
}
```

**Example (invalid)**

```json theme={null}
{
  "iban": "DE00370400440532013000",
  "valid": false,
  "error": "Checksum failed"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Invalid IBAN format or check digit mismatch"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## cURL example

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/iban-validator \
  -H "X-API-Key: bun_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"iban": "DE89370400440532013000"}'
```