{"openapi":"3.1.0","info":{"title":"Generate Random IBAN API","version":"1.1.0","summary":"Generate and validate structurally valid test IBANs.","description":"A small, versioned JSON API for generating and validating structurally valid (ISO 13616 / MOD-97) IBANs for 91 countries, with correct national check digits where the country defines them. An optional realistic mode uses real bank codes and digits only. Generated IBANs always pass checksum validation but were not issued by any bank: they are for testing, QA and education only, never for payments.","contact":{"name":"Generate Random IBAN","email":"apis@generaterandomiban.com","url":"https://generaterandomiban.com/en/apis"},"termsOfService":"https://generaterandomiban.com/en/privacy-policy"},"servers":[{"url":"https://generaterandomiban.com/api/v1","description":"Production API v1"}],"externalDocs":{"description":"Human-readable API documentation","url":"https://generaterandomiban.com/en/apis/docs"},"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Service","description":"Service discovery"},{"name":"Countries","description":"Supported countries and IBAN formats"},{"name":"Generation","description":"Generate random IBANs"},{"name":"Validation","description":"Validate IBANs"}],"paths":{"/":{"get":{"tags":["Service"],"operationId":"getServiceIndex","summary":"Service index (public, no key required).","security":[],"responses":{"200":{"description":"Service metadata and endpoint list."}}}},"/openapi.json":{"get":{"tags":["Service"],"operationId":"getOpenApi","summary":"This OpenAPI document (public, no key required).","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document."}}}},"/countries":{"get":{"tags":["Countries"],"operationId":"listCountries","summary":"List all supported countries and their IBAN formats.","responses":{"200":{"description":"The list of supported countries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountryList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/countries/{code}":{"get":{"tags":["Countries"],"operationId":"getCountry","summary":"A single country's IBAN format.","parameters":[{"name":"code","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code.","schema":{"type":"string","enum":["DE","FR","IT","ES","NL","BE","GB","AT","CH","LU","LI","MC","SM","VA","AD","IE","GI","SE","NO","FI","DK","IS","EE","LV","LT","FO","GL","PT","GR","CY","MT","RO","BG","HR","SI","SK","CZ","HU","PL","AL","BA","XK","ME","MK","RS","AZ","BY","GE","MD","RU","UA","SA","AE","JO","TR","BH","IQ","IL","KW","LB","OM","PS","QA","YE","DZ","TN","MA","EG","BI","DJ","LY","MR","MU","ST","SC","SO","SD","PK","KZ","MN","TL","BR","VG","CR","DO","SV","FK","GT","HN","NI","LC"]}}],"responses":{"200":{"description":"The country IBAN format.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"$ref":"#/components/schemas/Country"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/generate/{country}":{"get":{"tags":["Generation"],"operationId":"generateIbans","summary":"Generate one or more random IBANs for a country.","parameters":[{"name":"country","in":"path","required":true,"description":"ISO 3166-1 alpha-2 country code.","schema":{"type":"string","enum":["DE","FR","IT","ES","NL","BE","GB","AT","CH","LU","LI","MC","SM","VA","AD","IE","GI","SE","NO","FI","DK","IS","EE","LV","LT","FO","GL","PT","GR","CY","MT","RO","BG","HR","SI","SK","CZ","HU","PL","AL","BA","XK","ME","MK","RS","AZ","BY","GE","MD","RU","UA","SA","AE","JO","TR","BH","IQ","IL","KW","LB","OM","PS","QA","YE","DZ","TN","MA","EG","BI","DJ","LY","MR","MU","ST","SC","SO","SD","PK","KZ","MN","TL","BR","VG","CR","DO","SV","FK","GT","HN","NI","LC"]}},{"name":"count","in":"query","required":false,"description":"How many IBANs to return (1–100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":1}},{"name":"realistic","in":"query","required":false,"description":"Realistic mode: digits only in alphanumeric BBAN fields (except real bank codes that contain letters), and a real bank code of a major bank (for countries with curated codes) with a random account number. Such IBANs were not issued by any bank but could match a real account by chance: never use them for payments. National check digits are correct in both modes. Default true; pass 0 or false for fully random bank codes and accounts. Accepts 1/0 or true/false.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"The generated IBANs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/generate":{"post":{"tags":["Generation"],"operationId":"generateIbansBulk","summary":"Generate IBANs from a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["country"],"properties":{"country":{"type":"string","enum":["DE","FR","IT","ES","NL","BE","GB","AT","CH","LU","LI","MC","SM","VA","AD","IE","GI","SE","NO","FI","DK","IS","EE","LV","LT","FO","GL","PT","GR","CY","MT","RO","BG","HR","SI","SK","CZ","HU","PL","AL","BA","XK","ME","MK","RS","AZ","BY","GE","MD","RU","UA","SA","AE","JO","TR","BH","IQ","IL","KW","LB","OM","PS","QA","YE","DZ","TN","MA","EG","BI","DJ","LY","MR","MU","ST","SC","SO","SD","PK","KZ","MN","TL","BR","VG","CR","DO","SV","FK","GT","HN","NI","LC"]},"count":{"type":"integer","minimum":1,"maximum":100,"default":1},"realistic":{"type":"boolean","default":true,"description":"Realistic mode: digits only in alphanumeric BBAN fields (except real bank codes that contain letters), and a real bank code of a major bank (for countries with curated codes) with a random account number. Such IBANs were not issued by any bank but could match a real account by chance: never use them for payments. National check digits are correct in both modes."}}}}}},"responses":{"200":{"description":"The generated IBANs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/validate/{iban}":{"get":{"tags":["Validation"],"operationId":"validateIban","summary":"Validate an IBAN passed in the URL.","parameters":[{"name":"iban","in":"path","required":true,"description":"IBAN to validate (letters and digits, no spaces).","schema":{"type":"string","example":"DE89370400440532013000"}}],"responses":{"200":{"description":"The validation result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/validate":{"post":{"tags":["Validation"],"operationId":"validateIbanBody","summary":"Validate an IBAN from a JSON body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["iban"],"properties":{"iban":{"type":"string","example":"DE89 3704 0044 0532 0130 00"}}}}}},"responses":{"200":{"description":"The validation result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResult"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key issued on request. Send it in the X-API-Key header (an Authorization: Bearer token also works). Request a key by email at apis@generaterandomiban.com."}},"schemas":{"Country":{"type":"object","properties":{"code":{"type":"string","example":"DE"},"name":{"type":"string","example":"Germany"},"slug":{"type":"string","example":"germany"},"iban_length":{"type":"integer","example":22},"bban_length":{"type":"integer","example":18},"bban_format":{"type":"string","example":"8n10n"},"structure":{"type":"string","example":"DEkk bbbb bbbb cccc cccc cc"},"example":{"type":"string","example":"DE89370400440532013000"}}},"CountryList":{"type":"object","properties":{"count":{"type":"integer","example":46},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}},"Iban":{"type":"object","properties":{"iban":{"type":"string","example":"DE89370400440532013000"},"formatted":{"type":"string","example":"DE89 3704 0044 0532 0130 00"},"country":{"type":"string","example":"DE"},"check_digits":{"type":"string","example":"89"},"bban":{"type":"string","example":"370400440532013000"},"length":{"type":"integer","example":22},"valid":{"type":"boolean","example":true}}},"GenerateResult":{"type":"object","properties":{"country":{"type":"object","properties":{"code":{"type":"string","example":"DE"},"name":{"type":"string","example":"Germany"},"iban_length":{"type":"integer","example":22}}},"count":{"type":"integer","example":2},"realistic":{"type":"boolean","example":true,"description":"Whether realistic mode was used."},"ibans":{"type":"array","items":{"$ref":"#/components/schemas/Iban"}}}},"ValidateResult":{"type":"object","properties":{"iban":{"type":"string","example":"DE89370400440532013000"},"formatted":{"type":"string","example":"DE89 3704 0044 0532 0130 00"},"valid":{"type":"boolean","example":true},"country_code":{"type":"string","example":"DE"},"country_supported":{"type":"boolean","example":true},"check_digits":{"type":"string","example":"89"},"bban":{"type":"string","example":"370400440532013000"},"length":{"type":"integer","example":22},"expected_length":{"type":["integer","null"],"example":22},"checks":{"type":"object","properties":{"mod97":{"type":"boolean"},"length":{"type":["boolean","null"]},"format":{"type":"boolean"},"country_supported":{"type":"boolean"}}}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, revoked or expired API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Unknown country or endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Invalid":{"description":"Invalid parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit exceeded (default 60 requests/minute per key)."}}}}