Generate Random IBAN

API documentation

Generate and validate structurally valid test IBANs (ISO 13616, MOD-97) over HTTP. Every response is JSON. Generated IBANs are test data: no bank issued them.

Base URL

https://generaterandomiban.com/api/v1

Authentication

Every endpoint except the service index needs an API key. Send it in the X-API-Key header (Authorization: Bearer also works). Keep the key on your server and never ship it in client-side code.

curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries

Keys are issued by hand. Email us a short description of your use case and we will send you one.

apis@generaterandomiban.com

Rate limits

Limits apply per key: 60 requests per minute by default, or the custom limit set on your key. Above the limit the API answers with HTTP 429 (Too Many Requests).

Endpoints

GET /api/v1 Public

Service index with metadata and the list of endpoints. No API key needed.

Example request
curl https://generaterandomiban.com/api/v1
Example response
{
  "name": "Generate Random IBAN API",
  "version": "v1",
  "documentation": "https://generaterandomiban.com/en/apis/docs",
  "authentication": { "type": "api_key", "header": "X-API-Key" }
}

GET /api/v1/countries

Every supported country with its IBAN format.

Example request
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries
Example response
{
  "count": 91,
  "countries": [
    {
      "code": "DE",
      "name": "Germany",
      "slug": "germany",
      "iban_length": 22,
      "bban_length": 18,
      "bban_format": "8n10n",
      "structure": "DEkk bbbb bbbb cccc cccc cc",
      "example": "DE89370400440532013000"
    }
  ]
}

GET /api/v1/countries/{code}

The IBAN format of one country.

Parameter In Description
code path ISO 3166-1 alpha-2 country code, for example DE, FR or IT.
Example request
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/countries/DE
Example response
{
  "country": {
    "code": "DE",
    "name": "Germany",
    "iban_length": 22,
    "bban_format": "8n10n",
    "example": "DE89370400440532013000"
  }
}

GET /api/v1/generate/{country}

Generate one or more random, valid IBANs for a country.

National check digits (such as the French clé RIB, the Italian CIN or the Spanish DC) are computed in both modes. No bank issued the realistic IBANs, but one could match a real account by chance: never use them for payments.

Parameter In Description
country path ISO 3166-1 alpha-2 country code.
count query How many IBANs to return, from 1 to 100. Default: 1.
realistic query Optional. 1 or true for realistic IBANs: digits only and, where available, the real bank code of a major bank, with a random account number. 0 or false for fully random IBANs, with letters where the format allows them. Default: 1.
Example request
curl -H "X-API-Key: YOUR_KEY" "https://generaterandomiban.com/api/v1/generate/DE?count=2"
Example response
{
  "country": { "code": "DE", "name": "Germany", "iban_length": 22 },
  "count": 2,
  "realistic": true,
  "ibans": [
    {
      "iban": "DE89370400440532013000",
      "formatted": "DE89 3704 0044 0532 0130 00",
      "country": "DE",
      "check_digits": "89",
      "bban": "370400440532013000",
      "length": 22,
      "valid": true
    }
  ]
}

POST /api/v1/generate

Generate IBANs with the parameters in a JSON body.

Parameter In Description
country body ISO 3166-1 alpha-2 country code. Required.
count body How many IBANs to return, from 1 to 100. Default: 1.
realistic body Optional boolean, same as the realistic query parameter. Default: true.
Example request
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"FR","count":3,"realistic":true}' https://generaterandomiban.com/api/v1/generate
Example response
{
  "country": { "code": "FR", "name": "France", "iban_length": 27 },
  "count": 3,
  "realistic": true,
  "ibans": [ /* … */ ]
}

GET /api/v1/validate/{iban}

Validate an IBAN passed in the URL, without spaces.

Parameter In Description
iban path The IBAN to validate, letters and digits only.
Example request
curl -H "X-API-Key: YOUR_KEY" https://generaterandomiban.com/api/v1/validate/DE89370400440532013000
Example response
{
  "iban": "DE89370400440532013000",
  "valid": true,
  "country_code": "DE",
  "country_supported": true,
  "check_digits": "89",
  "bban": "370400440532013000",
  "length": 22,
  "expected_length": 22,
  "checks": { "mod97": true, "length": true, "format": true, "country_supported": true }
}

POST /api/v1/validate

Validate an IBAN sent in a JSON body. Spaces are allowed.

Parameter In Description
iban body The IBAN to validate. Required.
Example request
curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"iban":"DE89 3704 0044 0532 0130 00"}' https://generaterandomiban.com/api/v1/validate
Example response
{
  "iban": "DE89370400440532013000",
  "valid": true,
  "country_code": "DE",
  "checks": { "mod97": true, "length": true, "format": true, "country_supported": true }
}

Errors and status codes

Errors use standard HTTP status codes and a JSON body with an error object that holds a code and a message. The usual ones are 401 (missing or invalid key), 404 (unknown country or endpoint), 422 (invalid parameters) and 429 (rate limit exceeded).

{
  "error": {
    "code": "invalid_request",
    "message": "The \"count\" parameter must be an integer between 1 and 100."
  }
}

Download a list (no key)

The generator can also give you a file: up to 100 IBANs of one country as CSV, JSON, SQL (INSERT statements) or plain text, with one column per BBAN segment. It needs no API key and allows 30 downloads per minute.

Parameter In Description
countrypathISO 3166-1 alpha-2 country code.
formatquerycsv, json, sql or txt. Default: csv.
countqueryHow many IBANs, from 1 to 100. Default: 10.
realisticquery1 for realistic IBANs, 0 for fully random ones. Default: 1.
Example request
curl -OJ "https://generaterandomiban.com/export/de?format=csv&count=50"
Example response
iban,iban_print,country,check_digits,bank,account
DE89370400440532013000,DE89 3704 0044 0532 0130 00,DE,89,37040044,0532013000

MCP server

AI agents can use the same features through a Model Context Protocol server at /mcp (Streamable HTTP, JSON-RPC 2.0). It is public, needs no API key and accepts up to 120 requests per minute.

Tool Description
list_countriesList the supported countries with their IBAN length.
generate_ibanGenerate 1 to 100 test IBANs for a country.
validate_ibanCheck an IBAN: MOD-97, expected length and country support.
Example request
curl -X POST https://generaterandomiban.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"generate_iban","arguments":{"country":"IT","count":2}}}'

generate_iban also takes "realistic", which defaults to true. Pass "realistic": false for fully random IBANs.

Server card for discovery: /.well-known/mcp/server-card.json

OpenAPI specification

A machine-readable OpenAPI 3.1 description of the REST API, for client generators and API tools: /api/v1/openapi.json

JavaScript library

To validate IBANs in the browser or offline, without calling the API, use our open-source iban-check package for JavaScript and TypeScript (no dependencies, MIT licence): GitHub · npm

Terminal
npm install iban-check

Get an API key

Keys are issued by hand. Email us a short description of your use case and we will send you one.

Request an API key

We use cookies to enhance your experience

We and selected third parties use cookies or similar technologies for technical purposes and, with your consent, for site analytics.

You can freely give, deny or withdraw your consent at any time.

Read our Cookie policy and Privacy policy.