{
  "openapi": "3.1.0",
  "info": {
    "title": "ibanchecker.cash API",
    "version": "1.0.0",
    "description": "REST API for IBAN validation across 90 countries. Validate single IBANs, validate up to 100 IBANs per request, extract IBANs from free text, look up country format specifications, and resolve SWIFT/BIC codes. No IBAN data is stored or logged; all validation runs in memory at the edge.",
    "termsOfService": "https://ibanchecker.cash/terms",
    "contact": {
      "name": "ibanchecker.cash support",
      "url": "https://ibanchecker.cash/contact",
      "email": "koray.koylu@ibanchecker.cash"
    }
  },
  "servers": [{ "url": "https://ibanchecker.cash/api/v1" }],
  "security": [{ "bearerAuth": [] }, {}],
  "paths": {
    "/validate": {
      "post": {
        "operationId": "validateIban",
        "summary": "Validate a single IBAN",
        "description": "Validates an IBAN using the ISO 13616 MOD-97-10 checksum, country-specific length and structure rules, and returns the parsed BBAN plus bank identification (name, BIC, city) where available. Works without an API key at 100 requests/hour per IP; authenticated requests count against the plan quota.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["iban"],
                "properties": {
                  "iban": { "type": "string", "description": "IBAN to validate, with or without spaces", "examples": ["DE89370400440532013000"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Validation result",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResult" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/validate/bulk": {
      "post": {
        "operationId": "validateIbansBulk",
        "summary": "Validate up to 100 IBANs",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["ibans"],
                "properties": {
                  "ibans": {
                    "type": "array",
                    "items": { "type": "string" },
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Array of IBANs to validate"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Array of validation results in the same order as the request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationResult" } }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/extract": {
      "post": {
        "operationId": "extractIbans",
        "summary": "Extract and validate IBANs from free text",
        "description": "Scans up to 50,000 characters of text (emails, invoices, documents) for IBAN-shaped strings and validates each candidate.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": { "type": "string", "maxLength": 50000, "description": "Free text to scan for IBANs" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "IBANs found in the text with validation results",
            "content": { "application/json": { "schema": { "type": "object" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/formats/{country}": {
      "get": {
        "operationId": "getIbanFormat",
        "summary": "Get the IBAN format specification for a country",
        "security": [{}],
        "parameters": [
          {
            "name": "country",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 2, "maxLength": 2 },
            "description": "ISO 3166-1 alpha-2 country code, e.g. DE",
            "example": "de"
          }
        ],
        "responses": {
          "200": {
            "description": "Format specification",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "country_code": { "type": "string" },
                    "country_name": { "type": "string" },
                    "length": { "type": "integer" },
                    "currency": { "type": "string" },
                    "currency_name": { "type": "string" },
                    "sepa": { "type": "boolean" },
                    "swift": { "type": "boolean" },
                    "format_string": { "type": "string" },
                    "example": { "type": "string" },
                    "bban_fields": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "label": { "type": "string" },
                          "length": { "type": "integer" }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/swift/{bic}": {
      "get": {
        "operationId": "lookupBic",
        "summary": "Look up a SWIFT/BIC code",
        "security": [{}],
        "parameters": [
          {
            "name": "bic",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "minLength": 8, "maxLength": 11 },
            "description": "8 or 11 character ISO 9362 BIC",
            "example": "DEUTDEFF"
          }
        ],
        "responses": {
          "200": {
            "description": "Bank record for the BIC",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bic": { "type": "string" },
                    "bic8": { "type": "string" },
                    "bank_code": { "type": "string" },
                    "country_code": { "type": "string" },
                    "location_code": { "type": "string" },
                    "branch_code": { "type": ["string", "null"] },
                    "bank_name": { "type": "string" },
                    "city": { "type": ["string", "null"] },
                    "country_name": { "type": "string" },
                    "sepa": { "type": ["boolean", "null"] },
                    "type": { "type": ["string", "null"] },
                    "status": { "type": ["string", "null"] }
                  }
                }
              }
            }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key issued at https://ibanchecker.cash/api-docs. Optional: without a key, requests are limited to 100/hour per IP."
      }
    },
    "schemas": {
      "ValidationResult": {
        "type": "object",
        "description": "Result of validating one IBAN. When valid is false, only iban, formatted, country, country_name, error and error_code are present.",
        "properties": {
          "valid": { "type": "boolean" },
          "iban": { "type": "string" },
          "formatted": { "type": ["string", "null"], "description": "IBAN grouped in blocks of four characters" },
          "check_digits": { "type": "string" },
          "bban": { "type": "string" },
          "country": { "type": ["string", "null"] },
          "country_name": { "type": ["string", "null"] },
          "bank_name": { "type": ["string", "null"] },
          "bank_type": { "type": ["string", "null"] },
          "bic": { "type": ["string", "null"] },
          "bank_city": { "type": ["string", "null"] },
          "bank_code": { "type": ["string", "null"] },
          "branch_code": { "type": ["string", "null"] },
          "account_number": { "type": ["string", "null"] },
          "currency": { "type": ["string", "null"] },
          "currency_name": { "type": ["string", "null"] },
          "transfer_type": { "type": ["string", "null"] },
          "sepa": { "type": ["boolean", "null"] },
          "flag": { "type": ["string", "null"] },
          "error": { "type": "string" },
          "error_code": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "error_code": { "type": "string" }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Malformed request",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Unauthorized": {
        "description": "Invalid or inactive API key",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Rate limit or monthly quota exceeded",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}