{ "openapi": "3.1.0", "info": { "title": "ibanlint", "version": "1.0.0", "summary": "IBAN validation, bank directories and payment QR codes over HTTP.", "description": "Every tool on ibanlint.com, callable directly. No key, no account and no state: each request is answered from data bundled with the deployment, and nothing is stored.\n\nA malformed IBAN is not an HTTP error. `GET /validate` answers 200 with `valid: false` and an `error_code` naming which check failed — only a missing parameter is a 400. That distinction is deliberate: a caller validating a thousand accounts should not have to treat nine hundred of them as transport failures.\n\nNulls mean *unknown*, never *wrong*. An unlisted bank leaves `bank_name` null; a country with no published check digit reports `national_check_valid: null` rather than guessing.", "license": { "name": "MIT" } }, "servers": [ { "url": "https://www.ibanlint.com", "description": "This deployment" } ], "tags": [ { "name": "Verify" }, { "name": "Build" }, { "name": "Look up" }, { "name": "Explain" } ], "paths": { "/api/v1/validate": { "get": { "operationId": "getValidate", "tags": [ "Verify" ], "summary": "Validate one IBAN", "description": "Checks length, structure and mod-97, then the country's own check digits where one is published, and enriches the result from the bundled bank directory. A malformed IBAN is HTTP 200 with valid:false — only a missing iban parameter is a 400.\n\nExample: `/api/v1/validate?iban=DE89370400440532013000`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN to act on. Spaces and punctuation are ignored.", "schema": { "type": "string" }, "example": "DE89370400440532013000" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } }, "post": { "operationId": "postValidate", "tags": [ "Verify" ], "summary": "Validate one IBAN (body)", "description": "The same check, for callers that would rather not put an account number in a URL.\n\nExample: `/api/v1/validate`", "requestBody": { "required": true, "content": { "application/json": { "example": { "iban": "DE89370400440532013000" }, "schema": { "type": "object", "required": [ "iban" ], "properties": { "iban": { "description": "The IBAN to validate.", "type": "string" } } } } } }, "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/validate/bulk": { "get": { "operationId": "getValidateBulk", "tags": [ "Verify" ], "summary": "Validate many IBANs", "description": "Repeat the iban parameter once per account. Returns the same result object for each, plus valid and invalid counts.\n\nExample: `/api/v1/validate/bulk?iban=DE89370400440532013000&iban=GB29NWBK60161331926819`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "Repeatable. One IBAN per occurrence.", "schema": { "type": "string" }, "example": "DE89370400440532013000" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } }, "post": { "operationId": "postValidateBulk", "tags": [ "Verify" ], "summary": "Validate many IBANs (body)", "description": "The same, with the list in a JSON body. Preferred for more than a handful.\n\nExample: `/api/v1/validate/bulk`", "requestBody": { "required": true, "content": { "application/json": { "example": { "ibans": [ "DE89370400440532013000", "GB29NWBK60161331926819", "NOPE" ] }, "schema": { "type": "object", "required": [ "ibans" ], "properties": { "ibans": { "description": "The IBANs to validate.", "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/extract": { "post": { "operationId": "postExtract", "tags": [ "Verify" ], "summary": "Find IBANs in free text", "description": "Scans prose — an email, an invoice, a chat log — and validates every candidate it finds. The text is processed in the request and discarded.\n\nExample: `/api/v1/extract`", "requestBody": { "required": true, "content": { "application/json": { "example": { "text": "Please pay DE89 3704 0044 0532 0130 00 by Friday. Old account was GB29 NWBK 6016 1331 9268 19." }, "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "description": "The text to scan.", "type": "string" } } } } } }, "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/repair": { "get": { "operationId": "getRepair", "tags": [ "Verify" ], "summary": "Suggest a correction for a mistyped IBAN", "description": "Almost every real failure is one of four things — a wrong character, a missing one, an extra one, or two neighbours swapped. Returns only edits that produce a valid IBAN. unambiguous is true when exactly one does, which is the only case safe to apply without asking.\n\nExample: `/api/v1/repair?iban=DE89370400440532013001`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN to act on. Spaces and punctuation are ignored.", "schema": { "type": "string" }, "example": "DE89370400440532013000" }, { "name": "limit", "in": "query", "required": false, "description": "Maximum suggestions, 1-20. Defaults to 5.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/generate": { "get": { "operationId": "getGenerate", "tags": [ "Build" ], "summary": "Generate valid test IBANs", "description": "Structurally valid IBANs that satisfy mod-97 and, where one exists, the national check digit. They belong to no real account. Pass every_country=1 for one per country instead.\n\nExample: `/api/v1/generate?country=DE&count=3`", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO country code. Not required with every_country.", "schema": { "type": "string" }, "example": "DE" }, { "name": "count", "in": "query", "required": false, "description": "1-50. Defaults to 1.", "schema": { "type": "integer" } }, { "name": "letters", "in": "query", "required": false, "description": "Allow letters where the structure permits them. Off by default.", "schema": { "type": "boolean" } }, { "name": "every_country", "in": "query", "required": false, "description": "One IBAN for every country that allows generation.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/convert": { "get": { "operationId": "getConvert", "tags": [ "Build" ], "summary": "Build an IBAN from a domestic account", "description": "Deterministic construction for AE, BE, DE, FR, GB, NL, TR. Field names match what is printed on the documents a person reads from. Pass bban instead to assemble any country's IBAN from a raw BBAN.\n\nExample: `/api/v1/convert?country=DE&blz=37040044&account_number=0532013000`", "parameters": [ { "name": "country", "in": "query", "required": true, "description": "ISO country code.", "schema": { "type": "string" }, "example": "DE" }, { "name": "bban", "in": "query", "required": false, "description": "A raw BBAN. Wins over the fields below.", "schema": { "type": "string" } }, { "name": "blz", "in": "query", "required": false, "description": "DE: the Bankleitzahl.", "schema": { "type": "string" } }, { "name": "account_number", "in": "query", "required": false, "description": "DE, TR, FR, GB, NL, AE.", "schema": { "type": "string" } }, { "name": "bank_code", "in": "query", "required": false, "description": "TR, FR, GB, NL, AE.", "schema": { "type": "string" } }, { "name": "branch_code", "in": "query", "required": false, "description": "FR.", "schema": { "type": "string" } }, { "name": "rib_key", "in": "query", "required": false, "description": "FR: the two-digit RIB key.", "schema": { "type": "string" } }, { "name": "sort_code", "in": "query", "required": false, "description": "GB.", "schema": { "type": "string" } }, { "name": "domestic_number", "in": "query", "required": false, "description": "BE: 999-9999999-99.", "schema": { "type": "string" } }, { "name": "reserved_digit", "in": "query", "required": false, "description": "TR. Defaults to 0.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/qr": { "get": { "operationId": "getQr", "tags": [ "Build" ], "summary": "Build a payment QR", "description": "With a beneficiary name, an EPC069-12 payment payload a banking app can pre-fill. Without one, the plain IBAN — still scannable, and honest about carrying no payment. Returns the payload, its byte count and an SVG. The IBAN is validated first: a code built around a broken account number scans cleanly and fails at the bank.\n\nExample: `/api/v1/qr?iban=DE89370400440532013000&name=Example%20GmbH&amount=49.90`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN to act on. Spaces and punctuation are ignored.", "schema": { "type": "string" }, "example": "DE89370400440532013000" }, { "name": "name", "in": "query", "required": false, "description": "Beneficiary. Required for an EPC payload.", "schema": { "type": "string" } }, { "name": "amount", "in": "query", "required": false, "description": "Euro. Omit for an open amount.", "schema": { "type": "string" } }, { "name": "bic", "in": "query", "required": false, "description": "Defaults to the one derived from the IBAN.", "schema": { "type": "string" } }, { "name": "remittance", "in": "query", "required": false, "description": "Free text, up to 140 characters.", "schema": { "type": "string" } }, { "name": "reference", "in": "query", "required": false, "description": "ISO 11649. Excludes remittance.", "schema": { "type": "string" } }, { "name": "purpose", "in": "query", "required": false, "description": "ISO 20022 purpose code.", "schema": { "type": "string" } }, { "name": "note", "in": "query", "required": false, "description": "Up to 70 characters, for the beneficiary.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/qr/decode": { "post": { "operationId": "postQrDecode", "tags": [ "Build" ], "summary": "Read an EPC payload", "description": "Turns the twelve positional lines back into fields.\n\nExample: `/api/v1/qr/decode`", "requestBody": { "required": true, "content": { "application/json": { "example": { "payload": "BCD\n002\n1\nSCT\nCOBADEFFXXX\nExample GmbH\nDE89370400440532013000\nEUR49.9\n\n\nInvoice 2026-014\n" }, "schema": { "type": "object", "required": [ "payload" ], "properties": { "payload": { "description": "The EPC payload.", "type": "string" } } } } } }, "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/swift/{bic}": { "get": { "operationId": "getSwiftBic", "tags": [ "Look up" ], "summary": "Look up a BIC", "description": "The directory record behind a BIC. Unlike IBAN validation, a syntactically valid BIC that is not listed is a 404 rather than a 200 with null fields.\n\nExample: `/api/v1/swift/COBADEFF`", "parameters": [ { "name": "bic", "in": "path", "required": true, "description": "8 or 11 characters.", "schema": { "type": "string" }, "example": "COBADEFF" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/bic/parse": { "get": { "operationId": "getBicParse", "tags": [ "Look up" ], "summary": "Split a BIC structurally", "description": "Bank, country, location and branch, from the code alone. No directory is consulted, so this answers for codes that are not listed.\n\nExample: `/api/v1/bic/parse?bic=COBADEFFXXX`", "parameters": [ { "name": "bic", "in": "query", "required": true, "description": "8 or 11 characters.", "schema": { "type": "string" }, "example": "COBADEFFXXX" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/bic/of": { "get": { "operationId": "getBicOf", "tags": [ "Look up" ], "summary": "Derive the BIC for an IBAN", "description": "The BIC the bundled directory holds for that bank code. Null when the bank is not listed — never a guess, because a wrong BIC routes money to the wrong institution.\n\nExample: `/api/v1/bic/of?iban=DE89370400440532013000`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN to act on. Spaces and punctuation are ignored.", "schema": { "type": "string" }, "example": "DE89370400440532013000" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/banks": { "get": { "operationId": "getBanks", "tags": [ "Look up" ], "summary": "Search the bank directory", "description": "By name, BIC or city. Pass country alone to list a country's institutions alphabetically — browsing a country is a different question from searching with a blank term.\n\nExample: `/api/v1/banks?q=commerzbank`", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Name, BIC or city.", "schema": { "type": "string" }, "example": "commerzbank" }, { "name": "country", "in": "query", "required": false, "description": "ISO country code.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1-200. Defaults to 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/banks/{slug}": { "get": { "operationId": "getBanksSlug", "tags": [ "Look up" ], "summary": "One institution", "description": "The directory entry and its full BIC record.\n\nExample: `/api/v1/banks/commerzbank-ag`", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Directory slug.", "schema": { "type": "string" }, "example": "commerzbank-ag" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/bics": { "get": { "operationId": "getBics", "tags": [ "Look up" ], "summary": "Search the SWIFT/BIC directory", "description": "The same search over BIC records rather than institutions.\n\nExample: `/api/v1/bics?country=TR&limit=5`", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Code, institution or city.", "schema": { "type": "string" } }, { "name": "country", "in": "query", "required": false, "description": "ISO country code.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1-200. Defaults to 25.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/bank-info/{bic}": { "get": { "operationId": "getBank-infoBic", "tags": [ "Look up" ], "summary": "Bank name for a BIC, tersely", "description": "The lookup the site's own interface uses. Never fails: an unknown BIC is found:false with HTTP 200.\n\nExample: `/api/v1/bank-info/COBADEFF`", "parameters": [ { "name": "bic", "in": "path", "required": true, "description": "8 or 11 characters.", "schema": { "type": "string" }, "example": "COBADEFF" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/countries": { "get": { "operationId": "getCountries", "tags": [ "Explain" ], "summary": "Every IBAN country", "description": "Length, currency, SEPA membership and a published example, per country.\n\nExample: `/api/v1/countries`", "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/countries/{code}": { "get": { "operationId": "getCountriesCode", "tags": [ "Explain" ], "summary": "One country's format", "description": "The registered length, the BBAN field layout, and the format mask — k check digit, n digit, A letter, c alphanumeric.\n\nExample: `/api/v1/countries/DE`", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "ISO country code.", "schema": { "type": "string" }, "example": "DE" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/domestic": { "get": { "operationId": "getDomestic", "tags": [ "Explain" ], "summary": "The account in its domestic form", "description": "German BLZ and Kontonummer, a British sort code and account number, and so on. Null when the country publishes no domestic presentation — that is a property of the country, not a missing answer.\n\nExample: `/api/v1/domestic?iban=DE89370400440532013000`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN to act on. Spaces and punctuation are ignored.", "schema": { "type": "string" }, "example": "DE89370400440532013000" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/mask": { "get": { "operationId": "getMask", "tags": [ "Explain" ], "summary": "Mask an IBAN for display", "description": "Keeps the country, the check digits and a configurable tail. For logs and screenshots.\n\nExample: `/api/v1/mask?iban=DE89370400440532013000&tail=4`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN to act on. Spaces and punctuation are ignored.", "schema": { "type": "string" }, "example": "DE89370400440532013000" }, { "name": "tail", "in": "query", "required": false, "description": "Visible trailing characters, 0-8. Defaults to 4.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/describe": { "get": { "operationId": "getDescribe", "tags": [ "Explain" ], "summary": "Describe an account in a sentence", "description": "One line for a confirmation screen. Degrades as detail runs out rather than inventing any.\n\nExample: `/api/v1/describe?iban=DE89370400440532013000`", "parameters": [ { "name": "iban", "in": "query", "required": true, "description": "The IBAN to act on. Spaces and punctuation are ignored.", "schema": { "type": "string" }, "example": "DE89370400440532013000" } ], "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } }, "/api/v1/coverage": { "get": { "operationId": "getCoverage", "tags": [ "Explain" ], "summary": "What the datasets contain", "description": "Counts per dataset and per country. A caller deciding whether to trust a null needs to know how much of the directory exists.\n\nExample: `/api/v1/coverage`", "responses": { "200": { "description": "The result. Shapes follow the library's own types.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Unprocessable" } } } } }, "components": { "schemas": { "ApiError": { "type": "object", "description": "Returned with every 4xx. `error` is written for a person; `error_code` is the stable value to branch on.", "required": [ "error", "error_code" ], "properties": { "error": { "type": "string" }, "error_code": { "type": "string", "enum": [ "MISSING_IBAN", "INVALID_COUNTRY", "INVALID_LENGTH", "INVALID_FORMAT", "INVALID_CHECK_DIGITS", "COUNTRY_NOT_FOUND", "BIC_NOT_FOUND", "MISSING_PARAMETER", "INVALID_PARAMETER", "UNSUPPORTED_COUNTRY", "BANK_NOT_FOUND", "NOT_FOUND", "METHOD_NOT_ALLOWED" ] } } } }, "responses": { "BadRequest": { "description": "A required parameter or body field was missing or unusable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "NotFound": { "description": "No such endpoint, country, BIC or institution.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "Unprocessable": { "description": "The request was understood but cannot be carried out — an IBAN that does not validate, or a country with no published construction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }