SWIFT IBANs API

openapi: 3.2.0
info:
  title: Swift IBANs API
  version: '1.0'
  description: 'Operations tagged IBANs 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: IBANs
  description: IBAN (International Bank Account Number) lookup and validation
paths:
  /v2/ibans/{iban}:
    get:
      operationId: getIban
      summary: Get IBAN Details
      description: Returns details for an IBAN including the associated BIC, bank name, and account holder country.
      tags:
      - IBANs
      parameters:
      - $ref: '#/components/parameters/iban'
      responses:
        '200':
          description: IBAN details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IbanDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '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
  /v2/ibans/{iban}/validity:
    get:
      operationId: validateIban
      summary: Validate IBAN
      description: Validates an IBAN by checking its format, check digits, country code, and BBAN structure.
      tags:
      - IBANs
      parameters:
      - $ref: '#/components/parameters/iban'
      responses:
        '200':
          description: IBAN validity result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidityResult'
        '400':
          $ref: '#/components/responses/BadRequest'
      security:
      - OAuth2: []
    servers:
    - url: https://api.swift.com/swiftrefdata
      description: SWIFT SwiftRef Production API
    - url: https://sandbox.swift.com/swiftrefdata
      description: SWIFT SwiftRef Sandbox
  /v2/ibans/{iban}/bic:
    get:
      operationId: getBicForIban
      summary: Get BIC for IBAN
      description: Returns the BIC associated with a given IBAN.
      tags:
      - IBANs
      parameters:
      - $ref: '#/components/parameters/iban'
      responses:
        '200':
          description: BIC for the IBAN
          content:
            application/json:
              schema:
                type: object
                properties:
                  bic:
                    type: string
                    description: Bank Identifier Code
        '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
  /v2/iban_national_ids/{iban_national_id}/bic:
    get:
      operationId: getBicForIbanNationalId
      summary: Get BIC for IBAN National ID
      description: Returns the BIC associated with an IBAN national ID component.
      tags:
      - IBANs
      parameters:
      - name: iban_national_id
        in: path
        required: true
        schema:
          type: string
        description: IBAN national ID component
      responses:
        '200':
          description: BIC for the IBAN national ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  bic:
                    type: string
      security:
      - OAuth2: []
    servers:
    - url: https://api.swift.com/swiftrefdata
      description: SWIFT SwiftRef Production API
    - url: https://sandbox.swift.com/swiftrefdata
      description: SWIFT SwiftRef Sandbox
  /ibans/{iban}/validity:
    get:
      tags:
      - IBANs
      summary: Check validity of an IBAN, with SEPA-only option
      description: You can check whether an IBAN is valid, by restricting validation to SEPA countries.
      operationId: getIbanValidity
      parameters:
      - in: path
        name: iban
        schema:
          $ref: '#/components/schemas/Iban'
        required: true
        description: IBAN to validate
      - in: query
        name: sepa_only
        schema:
          $ref: '#/components/schemas/BooleanAsString'
        required: false
        description: Whether the IBAN validation must be restricted to SEPA countries
      responses:
        '200':
          description: Valid IBAN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IbanValidity'
            application/xml:
              schema:
                $ref: '#/components/schemas/IbanValidity'
        '400':
          description: Input IBAN is formally invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.MIRI
                  severity: Fatal
                  text: Invalid IBAN resource identifier (not matching expression [a-zA-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}) or missing IBAN resource identifier
                  user_message: Wrong URL format
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.MIRI</code> <severity>Fatal</severity> <text>Invalid IBAN resource identifier (not matching expression [a-zA-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}) or missing IBAN resource identifier</text> <user_message>Wrong URL format</user_message> </error> </errors>
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: Supplied IBAN is not valid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.IICC
                  severity: Fatal
                  text: ISO IBAN country code prefix 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.IICC</code> <severity>Fatal</severity> <text>ISO IBAN country code prefix is not valid</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
  /ibans/{iban}/bic:
    get:
      tags:
      - IBANs
      summary: Get the BIC for an IBAN
      description: For a given IBAN, you can retrieve the BIC of the institution that services the IBAN. This API is compliant with the requirement for BIC from IBAN derivation defined in the Regulation (EU) No 260/2012.
      operationId: getBicFromIban
      parameters:
      - in: path
        name: iban
        schema:
          $ref: '#/components/schemas/Iban'
        required: true
        description: IBAN for which the corresponding BIC is requested
      responses:
        '200':
          description: Corresponding BIC found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IbanBic'
            application/xml:
              schema:
                $ref: '#/components/schemas/IbanBic'
        '400':
          description: Input IBAN is formally invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.MIRI
                  severity: Fatal
                  text: Invalid IBAN resource identifier (not matching expression [a-zA-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}) or missing IBAN resource identifier
                  user_message: Wrong URL format
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.MIRI</code> <severity>Fatal</severity> <text>Invalid IBAN resource identifier (not matching expression [a-zA-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}) or missing IBAN resource identifier</text> <user_message>Wrong URL format</user_message> </error> </errors>
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: No corresponding BIC found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.BINF
                  severity: Fatal
                  user_message: No corresponding BIC found
                  text: The supplied IBAN does not exist or has no BIC associated
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.BINF</code> <severity>Fatal</severity> <text>No corresponding BIC found</text> <user_message>The supplied IBAN does not exist or has no BIC associated</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
  /ibans/{iban}:
    get:
      tags:
      - IBANs
      summary: Get details for an IBAN
      description: For a given IBAN, you can obtain the components of the IBAN.
      operationId: getIbanDetails
      parameters:
      - in: path
        name: iban
        schema:
          $ref: '#/components/schemas/Iban'
        required: true
        description: IBAN for which details are requested
      responses:
        '200':
          description: Corresponding IBAN found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IbanDetailsWithIsoFlag'
            application/xml:
              schema:
                $ref: '#/components/schemas/IbanDetailsWithIsoFlag'
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: No corresponding IBAN found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.INVI
                  severity: Fatal
                  text: Invalid IBAN
                  user_message: Invalid IBAN
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.INVI</code> <severity>Fatal</severity> <text>Invalid IBAN</text> <user_message>Invalid IBAN</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
  /ibans:
    get:
      tags:
      - IBANs
      summary: IBAN constructor
      description: Build a valid IBAN from BBAN elements (e.g. bank code, branch code, account number). Required BBAN elements depend on the country.
      operationId: ibanConstructor
      parameters:
      - $ref: '#/components/parameters/ibanCountryCode'
      - in: query
        name: bban_elements
        description: BBAN elements, supplied either as separate tokens or as single token (full BBAN).
        schema:
          type: object
          additionalProperties:
            type: string
            pattern: ^[0-9A-Z]{1,30}$
          maxProperties: 10
        examples:
          IT_separate_tokens:
            summary: Italian BBAN as separate elements
            value:
              checksum: X
              bank_code: 05428
              branch_code: '11101'
              account: '000000123456'
          IT_single_token:
            summary: Italian BBAN as single element (full BBAN)
            value:
              bban: X0542811101000000123456
      responses:
        '200':
          description: IBAN code was successfully built from BBAN elements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IbanBuilt'
            application/xml:
              schema:
                $ref: '#/components/schemas/IbanBuilt'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.MIBE
                  severity: Fatal
                  text: account not provided
                - code: REDA.API.MIBE
                  severity: Fatal
                  text: bank_code not provided
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.MIBE</code> <severity>Fatal</severity> <text>account not provided</text> </error> <error> <code>REDA.API.MIBE</code> <severity>Fatal</severity> <text>bank_code not provided</text> </error> </errors>
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: IBAN contruction failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.IBEV
                  severity: Fatal
                  text: country_code has an invalid value
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.MIBE</code> <severity>Fatal</severity> <text>country_code has an invalid value</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:
  schemas:
    IbanDetails:
      type: object
      properties:
        iban:
          type: string
          description: International Bank Account Number
        bic:
          type: string
          description: Associated BIC
        countryCode:
          type: string
          description: Country code from IBAN
        bankCode:
          type: string
          description: Bank code extracted from IBAN
        accountNumber:
          type: string
          description: Account number extracted from IBAN
    ValidityResult:
      type: object
      properties:
        valid:
          type: boolean
          description: Whether the identifier is valid
        errorCode:
          type: string
          description: Error code if invalid
        errorDescription:
          type: string
          description: Human-readable description of validation failure
    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
    IbanValidity:
      type: object
      required:
      - iban
      - validity
      properties:
        iban:
          $ref: '#/components/schemas/Iban'
        validity:
          type: string
          enum:
          - IVAL
          description: The code IVAL if the IBAN is valid
      xml:
        name: validity
      additionalProperties: false
      example:
        iban: IT60X0542811101000000123456
        validity: IVAL
    Bic:
      type: string
      description: Bank Identifier Code - ISO 9362
      pattern: ^[A-Z]{6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3})?$
      example: SWHTBEBBXXX
    CountryCode:
      type: string
      pattern: ^[a-zA-Z]{2}$
      description: 2-character ISO 3166-1 country code
      example: DE
    IbanDetailsWithIsoFlag:
      type: object
      required:
      - iban
      - country_code
      - checksum
      - bank_id
      - account_number
      - length
      - is_iso
      properties:
        iban:
          $ref: '#/components/schemas/Iban'
        country_code:
          $ref: '#/components/schemas/CountryCode'
        checksum:
          $ref: '#/components/schemas/TwoDigitCode'
        bank_id:
          $ref: '#/components/schemas/AlphaNumStringMax30'
        branch_id:
          $ref: '#/components/schemas/AlphaNumStringMax30'
        account_number:
          $ref: '#/components/schemas/AlphaNumStringMax30'
        length:
          type: integer
          minimum: 5
          maximum: 34
          description: The length of the IBAN
        is_iso:
          type: boolean
          description: Whether the IBAN format for the country has been officially registered with ISO (ISO 13616)
      xml:
        name: iban
      example:
        iban: DE04500700100532013000
        country_code: DE
        checksum: '04'
        bank_id: '50070010'
        account_number: '0532013000'
        length: 22
        is_iso: 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
    IbanBuilt:
      type: object
      required:
      - iban
      properties:
        iban:
          $ref: '#/components/schemas/Iban'
      xml:
        name: iban
      additionalProperties: false
      example:
        iban: IT60X0542811101000000123456
    Errors:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          minItems: 1
      xml:
        name: errors
      additionalProperties: false
    IbanBic:
      type: object
      required:
      - bic
      properties:
        bic:
          $ref: '#/components/schemas/Bic'
      xml:
        name: bic
      additionalProperties: false
      example:
        bic: DEUTDEFFXXX
    AlphaNumStringMax30:
      description: Alphanumeric string definition, from 1 to 30 characters long
      type: string
      pattern: ^[0-9a-zA-Z]{1,30}$
    TwoDigitCode:
      description: Generic 2-digit code
      type: string
      pattern: ^[0-9]{2}$
    StringMax255:
      description: Generic string definition, from 1 to 255 characters long
      type: string
      minLength: 1
      maxLength: 255
    BooleanAsString:
      type: string
      enum:
      - 'true'
      - 'false'
      example: 'true'
  responses:
    BadRequest:
      description: Bad request - invalid identifier format
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    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
  parameters:
    iban:
      name: iban
      in: path
      required: true
      schema:
        type: string
        pattern: ^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$
      description: IBAN (International Bank Account Number) without spaces
      example: DE89370400440532013000
    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