📚 Overview

• POST /api/v1/validate — Validate one or more IBANs. See details
• POST /api/v1/analyze — Validate and extract detailed info from one or more IBANs. See details
• GET /api/v1/countries — Get list of supported IBAN countries. See details
• GET /api/v1/countries/:country_code — Get detailed info for a specific country. See details
• GET /api/v1/banks/:country_code — Get all supported banks for a country. See details

🔐 Authentication

All endpoints require an API key passed via the X-Api-Key header.

You can find your API key in your dashboard.

curl -X POST https://iban-analyzer.com/api/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{"iban": "HR1210010051863000160"}'

✅ Validate IBANs

Validates one or multiple IBANs. This request contributes to your IBAN validation credit usage. Use this endpoint when you only need to verify the structural correctness of an IBAN and not retrieve bank or country details.

Request

POST /api/v1/validate
      Content-Type: application/json
      X-Api-Key: YOUR_API_KEY

      Body:
      { "iban": "HR1210010051863000160" }

      or

      ["HR1210010051863000160", "DE89370400440532013000"]

Response

{
        "results": [
          {
            "iban": "HR1210010051863000160",
            "isValid": true,
            "validationBreakdown": {
              "ibanCheckDigitValid": true,
              "ibanMod97Valid": true,
              "lengthValid": true,
              "structureValid": true,
              "overallValid": true
            }
          }
        ]
      }

Response Fields

• iban: The input IBAN string after formatting (spaces removed, uppercase).
• isValid: Overall result of all validation checks. Will only be true if all checks in validationBreakdown pass.
• validationBreakdown: An object describing the result of each individual validation step.

validationBreakdown Fields

• ibanCheckDigitValid: Confirms that the check digits (characters 3–4 of the IBAN) are correct, computed according to ISO 7064 Mod 97-10.
• ibanMod97Valid: Validates the full IBAN using Mod 97 after rearranging the IBAN and converting letters to numbers.
• lengthValid: Checks if the IBAN’s length matches the expected number of characters for its country code.
• structureValid: Confirms the IBAN structure is supported and extractable for that country.
• overallValid: Will be true only if all the above checks return true.

🔍 Analyze IBANs

Validates and analyzes IBAN structure, country info, and bank info. This request contributes to your bank info credit usage.

Request

POST /api/v1/analyze
      Content-Type: application/json
      X-Api-Key: YOUR_API_KEY

      Body:
      { "iban": "HR3124020063211094260" }

Response

{
        "results": [
          {
            "iban": "HR3124020063211094260",
            "isValid": true,
            "validationBreakdown": {
              "ibanCheckDigitValid": true,
              "ibanMod97Valid": true,
              "lengthValid": true,
              "structureValid": true,
              "overallValid": true
            },
            "ibanDetails": {
              "iban": "HR3124020063211094260",
              "countryCode": "HR",
              "bankCode": "2402006",
              "accountNumber": "3211094260"
            },
            "countryInfo": {
              "code": "HR",
              "name": "Croatia",
              "sepaSupport": true
            },
            "bankDetails": {
              "bankName": "Erste & Steiermärkische Bank",
              "swiftCode": "ESBCHR22",
              "bankCity": "Rijeka",
              "bankAddress": "Jadranski trg 3a",
              "bankZipCode": "51000"
            }
          }
        ]
      }

Validation Breakdown Fields

• ibanCheckDigitValid: Verifies that the two check digits (characters 3–4 of the IBAN) match the expected value based on ISO 7064 Mod 97-10.
• ibanMod97Valid: Confirms that the IBAN passes the Mod 97 operation by rearranging the IBAN and converting letters to numbers.
• lengthValid: Checks that the IBAN length matches the expected number of characters for the country (e.g., 21 for HR, 22 for DE).
• structureValid: Confirms that the IBAN structure is supported for the country, and that it includes valid bank/account component extraction rules.
• overallValid: Returns true only if all the above checks passed.

IBAN Details Fields

• iban: The cleaned full IBAN (no spaces, uppercase).
• countryCode: Two-letter ISO country code (e.g. HR for Croatia).
• bankCode: Bank identifier extracted according to the country’s IBAN structure.
• accountNumber: Account number part of the IBAN, extracted according to the national structure.

Country Info Fields

• code: ISO 2-letter country code.
• name: Human-readable country name.
• sepaSupport: Indicates whether the country participates in SEPA (Single Euro Payments Area).

Bank Details Fields

• bankName: Official name of the bank.
• swiftCode: The bank’s SWIFT/BIC code.
• bankCity: City where the bank is located.
• bankAddress: Street address of the bank’s headquarters.
• bankZipCode: Postal code for the bank’s address.

🌍 Supported Countries

Returns a list of countries with IBAN validation and bank info support flags.

GET /api/v1/countries
X-Api-Key: YOUR_API_KEY

Response

[
  {
    "code": "HR",
    "name": "Croatia",
    "ibanValidationSupported": true,
    "bankInfoSupported": true
  },
  ...
]

📌 Country Info

Returns detailed IBAN specification for a specific country.

GET /api/v1/countries/GB
        X-Api-Key: YOUR_API_KEY

Response

{
        "code": "GB",
        "name": "United Kingdom",
        "ibanLength": 22,
        "ibanApprovedForIntlUse": true,
        "sepaSupport": true
        }

• ibanApprovedForIntlUse: Indicates that the IBAN format is officially recognized and standardized for this country in international transactions.
• sepaSupport: Specifies whether the country is part of the SEPA (Single Euro Payments Area), enabling euro bank transfers with reduced fees and faster processing.

🏦 Banks in a Country

Returns all supported banks for a country with details.

GET /api/v1/banks/HR
X-Api-Key: YOUR_API_KEY

Response

{
  "banks": [
    {
      "bankName": "Erste & Steiermärkische Bank",
      "swiftCode": "ESBCHR22",
      "bankCity": "Rijeka",
      "bankAddress": "Jadranski trg 3a",
      "bankZipCode": "51000"
    },
    ...
  ]
}

📈 Quota Usage Logic

To make our service more user-friendly and fair, we apply the following rules when counting your credit usage:

• Validation Requests (/api/v1/validate and IBAN validation inside /api/v1/analyze): Each request consumes 1 IBAN validation credit, even if the IBAN is invalid.
• Bank Information Requests (/api/v1/analyze): Credits are only deducted if a valid IBAN with matching bank information is found.
• If the IBAN is valid but we have no bank information for it, no bank information credit is deducted.
• If all IBANs in the request are invalid, only a validation credit is deducted, not a bank info credit.

This way, you are only charged for successful validations or when valuable bank information is returned.

🚫 Error Responses

401 Unauthorized
{
  "error": "Missing or invalid API key"
}

403 Forbidden
{
  "error": "Quota exceeded"
}

400 Bad Request
{
  "error": "No IBANs provided"
}