SWIFT

SWIFT BBANs API

BBAN to IBAN conversion

GitHub OpenAPI

Operations 3

GET /v2/bbans/{bban}/iban Get IBAN for BBAN #
GET /bbans/{bban}/iban Get the IBAN from a BBAN #
GET /bbans/elements Get BBAN elements of an IBAN country #

Documentation

📖
Documentation
https://developer.swift.com/apis/swiftref-api

Specifications

⚙
OpenAPI
https://artifacts.apis.io/swift/openapi/swift-bbans-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/swift:swift-bbans-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

swift-bbans-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Swift BBANs API
  version: '1.0'
  description: 'Operations tagged BBANs across 3 of this provider''s published API definitions: swift-swiftref-api-openapi.yml, swift-swiftref-api-v4-openapi.yml, swift-swiftref-api-v4-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.swift.com/swiftrefdata
  description: SWIFT SwiftRef Production API
- url: https://sandbox.swift.com/swiftrefdata
  description: SWIFT SwiftRef Sandbox
- url: https://api.swift.com/swiftrefdata/v4
  description: Live environment
- url: https://sandbox.swift.com/swiftrefdata/v4
  description: Sandbox environment
- url: https://api-test.swift.com/swiftrefdata/v4
  description: Test environment
tags:
- name: BBANs
  description: BBAN to IBAN conversion
paths:
  /v2/bbans/{bban}/iban:
    get:
      operationId: getIbanForBban
      summary: Get IBAN for BBAN
      description: Converts a Basic Bank Account Number (BBAN) to the corresponding IBAN format.
      tags:
      - BBANs
      parameters:
      - name: bban
        in: path
        required: true
        schema:
          type: string
        description: Basic Bank Account Number
      responses:
        '200':
          description: IBAN for the BBAN
          content:
            application/json:
              schema:
                type: object
                properties:
                  iban:
                    type: string
                    description: International Bank Account Number
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2: []
    servers:
    - url: https://api.swift.com/swiftrefdata
      description: SWIFT SwiftRef Production API
    - url: https://sandbox.swift.com/swiftrefdata
      description: SWIFT SwiftRef Sandbox
  /bbans/{bban}/iban:
    get:
      tags:
      - BBANs
      summary: Get the IBAN from a BBAN
      description: For a given Basic Bank Account Number (BBAN), you can retrieve the corresponding IBAN; you must also provide a country code.
      operationId: getIbanFromBban
      parameters:
      - in: path
        name: bban
        schema:
          $ref: '#/components/schemas/AlphaNumStringMax30'
        required: true
        description: BBAN for which the corresponding IBAN is requested
        example: '500700100532013000'
      - in: query
        name: country_code
        schema:
          $ref: '#/components/schemas/CountryCode'
        required: true
        description: The 2-character ISO 3166-1 country code of the country that issued the National ID
      responses:
        '200':
          description: Corresponding IBAN found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IbanOfBban'
            application/xml:
              schema:
                $ref: '#/components/schemas/IbanOfBban'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.ICCP
                  severity: Fatal
                  text: The supplied country code does not exist
                  user_message: Invalid country code parameter
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.ICCP</code> <severity>Fatal</severity> <text>The supplied country code does not exist</text> <user_message>Invalid country code parameter</user_message> </error> </errors>
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: No corresponding IBAN found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.IBNF
                  severity: Fatal
                  text: No corresponding IBAN found
                  user_message: No corresponding IBAN found
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.IBNF</code> <severity>Fatal</severity> <text>No corresponding IBAN found</text> <user_message>No corresponding IBAN found</user_message> </error> </errors>
        '405':
          $ref: '#/components/responses/InvalidHttpMethod'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
      - oauthBearerToken: []
    servers:
    - url: https://api.swift.com/swiftrefdata/v4
      description: Live environment
    - url: https://sandbox.swift.com/swiftrefdata/v4
      description: Sandbox environment
    - url: https://api-test.swift.com/swiftrefdata/v4
      description: Test environment
  /bbans/elements:
    get:
      tags:
      - BBANs
      summary: Get BBAN elements of an IBAN country
      description: Get all BBAN element combinations that can be used as input of IBAN constructor for a specific country. Each BBAN element is described by name, length, mandatory/optional flag, position within BBAN.
      operationId: getBbanElements
      parameters:
      - $ref: '#/components/parameters/ibanCountryCode'
      responses:
        '200':
          description: BBAN elements found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BbanElements'
            application/xml:
              schema:
                $ref: '#/components/schemas/BbanElements'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.ICCP
                  severity: Fatal
                  text: IBAN country code parameter is not valid
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.ICCP</code> <severity>Fatal</severity> <text>IBAN country code parameter is not valid</text> </error> </errors>
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: BBAN elements not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.BENF
                  severity: Fatal
                  text: No corresponding BBAN elements found
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.BENF</code> <severity>Fatal</severity> <text>No corresponding BBAN elements found</text> </error> </errors>
        '405':
          $ref: '#/components/responses/InvalidHttpMethod'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
      - oauthBearerToken: []
    servers:
    - url: https://api.swift.com/swiftrefdata/v4
      description: Live environment
    - url: https://sandbox.swift.com/swiftrefdata/v4
      description: Sandbox environment
    - url: https://api-test.swift.com/swiftrefdata/v4
      description: Test environment
components:
  responses:
    NotFound:
      description: Identifier not found in reference data
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    NotAcceptable:
      description: The server does not support the format asked by the consumer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: REDA.API.NOAC
              severity: Fatal
              text: Requested output format is not supported
    UnexpectedError:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        application/xml:
          schema:
            $ref: '#/components/schemas/Errors'
    InvalidHttpMethod:
      description: Request HTTP method is not accepted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: REDA.API.IREQ
              severity: Fatal
              text: Request performed with HTTP method other than GET
              user_message: Invalid request
    Unallowed:
      description: You do not have sufficient privileges to execute this service
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: REDA.API.ILIC
              severity: Fatal
              text: You do not have sufficient privileges to execute this service
              user_message: You do not have sufficient privileges to execute this service
  schemas:
    Iban:
      type: string
      minLength: 5
      maxLength: 34
      pattern: ^[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{1,30}$
      description: IBAN (International Bank Account Number)
      example: IT60X0542811101000000123456
    CountryCode:
      type: string
      pattern: ^[a-zA-Z]{2}$
      description: 2-character ISO 3166-1 country code
      example: DE
    BbanElementCombination:
      type: array
      minLength: 1
      items:
        $ref: '#/components/schemas/IbanElement'
      xml:
        name: elements
        wrapped: true
      example:
      - field_position: 3
        field_length: 1
        field_name: national_check_digit
        label_en: National check digit
        label_local: CIN
        is_max_length: false
        is_mandatory: false
      - field_position: 4
        field_length: 5
        field_name: bank_code
        label_en: Bank code
        label_local: ABI
        is_max_length: false
        is_mandatory: true
      - field_position: 5
        field_length: 5
        field_name: branch_code
        label_en: Branch code
        label_local: CAB
        is_max_length: false
        is_mandatory: true
      - field_position: 6
        field_length: 12
        field_name: account_number
        label_en: Account number
        label_local: Numero di conto
        is_max_length: true
        is_mandatory: true
    IbanElement:
      type: object
      required:
      - field_position
      - field_name
      - field_length
      - is_max_length
      - is_mandatory
      properties:
        field_position:
          type: number
          minimum: 1
          maximum: 34
          description: 1-based position of the element within an IBAN
          example: 3
        field_name:
          type: string
          pattern: ^[a-z0-9_]{1,64}$
          description: Machine-friendly element identifier
          example: national_check_digit
        label_en:
          $ref: '#/components/schemas/StringMax255'
        label_local:
          $ref: '#/components/schemas/StringMax255'
        field_length:
          type: number
          minimum: 1
          maximum: 30
          example: 1
        is_max_length:
          type: boolean
          description: If true, the element can be supplied shorter than how stated by field_length and it is left-padded with zeroes
          example: false
        is_mandatory:
          type: boolean
          description: If false, IBAN constructor can find its value
          example: false
      xml:
        name: element
      additionalProperties: false
      example:
        field_position: 5
        field_length: 12
        field_name: account_number
        label_en: Account number
        label_local: Numero di conto
        is_max_length: true
        is_mandatory: true
    Error:
      description: Custom error schema to support detailed error message.
      required:
      - code
      - severity
      - text
      type: object
      properties:
        severity:
          description: Specifies the severity of the error.
          type: string
          enum:
          - Fatal
          - Transient
          - Logic
        code:
          description: Specifies the custom error code as defined by the service provider.
          type: string
          minLength: 3
          maxLength: 70
        text:
          $ref: '#/components/schemas/StringMax255'
        user_message:
          $ref: '#/components/schemas/StringMax255'
        more_info:
          description: Specifies an URL to find more information about the error.
          type: string
          format: uri
      xml:
        name: error
      additionalProperties: false
      example:
        code: REDA.API.CODE
        severity: Fatal
        text: Error description
        user_message: User-friendly error description
    AlphaNumStringMax30:
      description: Alphanumeric string definition, from 1 to 30 characters long
      type: string
      pattern: ^[0-9a-zA-Z]{1,30}$
    Errors:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          minItems: 1
      xml:
        name: errors
      additionalProperties: false
    IbanOfBban:
      type: object
      required:
      - iban
      properties:
        iban:
          $ref: '#/components/schemas/Iban'
      xml:
        name: iban
      additionalProperties: false
      example:
        iban: DE04500700100532013000
    StringMax255:
      description: Generic string definition, from 1 to 255 characters long
      type: string
      minLength: 1
      maxLength: 255
    BbanElements:
      type: object
      required:
      - elements
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/BbanElementCombination'
      xml:
        name: bban
      example:
        elements:
        - - field_position: 3
            field_length: 23
            field_name: bban
            label_en: Bank code and account number
            label_local: Numero di conto
            is_max_length: false
            is_mandatory: true
        - - field_position: 3
            field_length: 1
            field_name: checksum
            label_en: National checksum
            label_local: CIN
            is_max_length: false
            is_mandatory: false
          - field_position: 4
            field_length: 5
            field_name: bank_code
            label_en: Bank code
            label_local: ABI
            is_max_length: false
            is_mandatory: true
          - field_position: 5
            field_length: 5
            field_name: branch_code
            label_en: Branch code
            label_local: CAB
            is_max_length: false
            is_mandatory: true
          - field_position: 6
            field_length: 12
            field_name: account
            label_en: Account number
            label_local: Numero di conto corrente
            is_max_length: true
            is_mandatory: true
  parameters:
    ibanCountryCode:
      name: country_code
      in: query
      description: The 2-character ISO 3166-1 country code of an IBAN country
      schema:
        $ref: '#/components/schemas/CountryCode'
      required: true
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://api.swift.com/oauth2/v1/token
          scopes:
            urn:swiftref:external: External customer access to SwiftRef data
            urn:swiftref:internal: Internal payment validation access
    oauthBearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque OAuth 2.0
      description: "Use the access token obtained as a result of OAuth 2.0 flows. \n\nSWIFT supports two OAuth grant types depending on the API service.\n* JWT-Bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523)\n* Password grant type\n\nThis API uses password grant type.\n\nPlease visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) for more information and examples.\n\nIn this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.\n"
externalDocs:
  description: SWIFT SwiftRef API Documentation
  url: https://developer.swift.com/apis/swiftref-api
x-refined-from:
- swift-swiftref-api-openapi.yml
- swift-swiftref-api-v4-openapi.yml
- swift-swiftref-api-v4-openapi.yml