Random IBAN Generator Countries API

openapi: 3.2.0
info:
  title: Generate Random IBAN Countries 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
security:
- ApiKeyAuth: []
tags:
- name: Countries
  description: Supported countries and IBAN formats
paths:
  /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'
components:
  responses:
    NotFound:
      description: Unknown country or endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded (default 60 requests/minute per key).
    Unauthorized:
      description: Missing, invalid, revoked or expired API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
    CountryList:
      type: object
      properties:
        count:
          type: integer
          example: 46
        countries:
          type: array
          items:
            $ref: '#/components/schemas/Country'
    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
  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.'
externalDocs:
  description: Human-readable API documentation
  url: https://generaterandomiban.com/en/apis/docs