---
title: "IBAN structure template for a country (free)"
method: GET
path: "/v1/iban/structure/{country}"
tags: ["Free"]
---

# IBAN structure template for a country (free)

`GET /v1/iban/structure/{country}`

FREE metadata endpoint: returns the IBAN structural template for a country — total IBAN length, BBAN field positions (bank code / branch code / account number, 0-indexed within the BBAN), SEPA membership + schemes + VoP obligation, and a canonical example IBAN to copy-paste. Use it when an agent needs to know the IBAN format for a country before crafting a validation call.

## Path parameters

- `country` string, required

## Response `200`

IBAN structure template

- object
  - `country` object, required
    - `code` string
    - `name` string
  - `iban_length` integer, required
  - `bban_length` integer, required
  - `bban` object, nullable — BBAN field positions, 0-indexed within the BBAN. null when no structure is declared for the country. charset uses SWIFT registry notation (n=digits, a=uppercase letters, c=alphanumeric, e.g. "5!n").
    - `bank_code` object
      - `start` integer
      - `length` integer
      - `charset` string, nullable
    - `branch_code` object
      - `start` integer
      - `length` integer
      - `charset` string, nullable
    - `account_number` object
      - `start` integer
      - `length` integer
      - `charset` string, nullable
  - `bban_pattern` string, nullable — Full BBAN pattern in SWIFT IBAN Registry notation (e.g. "5!n12!c") — what /v1/iban/validate enforces structurally on top of length + mod-97.
  - `sepa` object, required
    - `member` boolean
    - `schemes` string[]
    - `vop_required` boolean
  - `example_iban` string, nullable
  - `example_iban_note` string, nullable — Says what example_iban is: an illustration from the SWIFT IBAN Registry whose bank code is not guaranteed to be allocated. 36 of the 89 come back bank_code_check.status not_in_register, which is the example being fictional rather than a gap in our data. LV uses the literal 'BANK', RO uses 'AAAA', and the Swiss one is proven unallocated by the SIX BankMaster.
  - `notes` string
  - `upgrade_hint` string
  - `cost_usdc` number, required

## Other responses

- `400` — Invalid country code (must be 2 letters), or literal {country} placeholder sent unsubstituted
- `404` — Country not covered — see GET /v1/iban/structure for the full list

---

[API](https://skmtc.net/ibanforge/apis/ibanforge-api.md) · [All operations](https://skmtc.net/ibanforge/apis/ibanforge-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ibanforge/ibanforge-api/versions/1d9e9674b3d2/schema)