SWIFT

SWIFT Country Codes API

Country code lookup and validation

GitHub OpenAPI

Operations 4

GET /v2/country_codes/{country_code} Get Country Code Details #
GET /v2/country_codes/{country_code}/validity Validate Country Code #
GET /country_codes/{country_code}/validity Check validity of a country code #
GET /country_codes/{country_code} Get details of a country code #

Documentation

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

Specifications

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

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/swift/json-schema/swift-country-code-details-schema.json
📊
JSONSchema
https://artifacts.apis.io/swift/json-schema/swift-validity-result-schema.json

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-country-codes-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-country-codes-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Swift Country Codes API
  version: '1.0'
  description: 'Operations tagged Country Codes 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: Country Codes
  description: Country code lookup and validation
paths:
  /v2/country_codes/{country_code}:
    get:
      operationId: getCountryCode
      summary: Get Country Code Details
      description: Returns details for an ISO 3166-1 alpha-2 country code including country name and IBAN structure.
      tags:
      - Country Codes
      parameters:
      - $ref: '#/components/parameters/countryCode'
      responses:
        '200':
          description: Country code details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryCodeDetails'
        '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/country_codes/{country_code}/validity:
    get:
      operationId: validateCountryCode
      summary: Validate Country Code
      description: Checks whether a country code is a valid ISO 3166-1 alpha-2 code.
      tags:
      - Country Codes
      parameters:
      - $ref: '#/components/parameters/countryCode'
      responses:
        '200':
          description: Country code validity result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidityResult'
      security:
      - OAuth2: []
    servers:
    - url: https://api.swift.com/swiftrefdata
      description: SWIFT SwiftRef Production API
    - url: https://sandbox.swift.com/swiftrefdata
      description: SWIFT SwiftRef Sandbox
  /country_codes/{country_code}/validity:
    get:
      tags:
      - Country Codes
      summary: Check validity of a country code
      description: You can check whether a country code is correct and valid.
      operationId: getCountryCodeValidity
      parameters:
      - in: path
        name: country_code
        schema:
          oneOf:
          - $ref: '#/components/schemas/TwoLetterCode'
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
        required: true
        description: Country code (2-letters, 3-letters or 3-digits) to validate
        example: DE
      responses:
        '200':
          description: Valid country code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountryCodeValidity'
            application/xml:
              schema:
                $ref: '#/components/schemas/CountryCodeValidity'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.MCRI
                  severity: Fatal
                  text: 'The country code is not in one of the three supported formats: 2a, 3a or 3n'
                  user_message: 'The country code is not in one of the three supported formats: 2a, 3a or 3n'
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: '<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.MCRI</code> <severity>Fatal</severity> <text>The country code is not in one of the three supported formats: 2a, 3a or 3n</text> <user_message>The country code is not in one of the three supported formats: 2a, 3a or 3n</user_message> </error> </errors>'
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: Invalid country code or country code not found or wrong URL format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.ICOC
                  severity: Fatal
                  text: The country code does not exist
                  user_message: The country code matches one of the three supported formats (2a, 3a or 3n), but it does not exist
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.ICOC</code> <severity>Fatal</severity> <text>The country code does not exist</text> <user_message>The country code matches one of the three supported formats (2a, 3a or 3n), but it does not exist</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
  /country_codes/{country_code}:
    get:
      tags:
      - Country Codes
      summary: Get details of a country code
      description: For a given country code, you can retrieve the details of that country code, that is the name, other codes and official currencies.
      operationId: getCountryCodeDetails
      parameters:
      - in: path
        name: country_code
        schema:
          oneOf:
          - $ref: '#/components/schemas/TwoLetterCode'
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
        required: true
        description: Country code (2-letters, 3-letters or 3-digits) for which details are requested
        example: DE
      responses:
        '200':
          description: Corresponding country code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Country'
            application/xml:
              schema:
                $ref: '#/components/schemas/Country'
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: No corresponding country code found or wrong URL format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.CONF
                  severity: Fatal
                  text: The country code does not exist
                  user_message: The country code does not exist
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.CONF</code> <severity>Fatal</severity> <text>The country code does not exist</text> <user_message>The country code does not exist</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
components:
  schemas:
    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
    CountryCodeDetails:
      type: object
      properties:
        countryCode:
          type: string
          description: ISO 3166-1 alpha-2 country code
        countryName:
          type: string
          description: Country name
        ibanLength:
          type: integer
          description: IBAN length for this country
        ibanStructure:
          type: string
          description: IBAN structure definition
    TwoLetterCode:
      description: Generic 2-letter code
      type: string
      pattern: ^[A-Z]{2}$
    CurrencyName:
      $ref: '#/components/schemas/StringMax70'
    StringMax70:
      description: Generic string definition, from 1 to 70 characters long
      type: string
      minLength: 1
      maxLength: 70
    ThreeLetterCode:
      description: Generic 3-letter code
      type: string
      pattern: ^[A-Z]{3}$
    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
    ThreeDigitCode:
      description: Generic 3-digit code
      type: string
      pattern: ^[0-9]{3}$
    Errors:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          minItems: 1
      xml:
        name: errors
      additionalProperties: false
    CountryCodeValidity:
      type: object
      required:
      - country_code
      - validity
      properties:
        country_code:
          oneOf:
          - $ref: '#/components/schemas/TwoLetterCode'
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
          description: The country code that was validated
        validity:
          type: string
          enum:
          - VCOC
          description: The code VCOC if the country code is valid
      xml:
        name: validity
      additionalProperties: false
      example:
        country_code: IT
        validity: VCOC
    Country:
      type: object
      required:
      - name
      - iso_2a_code
      properties:
        name:
          $ref: '#/components/schemas/CountryName'
        iso_2a_code:
          $ref: '#/components/schemas/TwoLetterCode'
        iso_3a_code:
          $ref: '#/components/schemas/ThreeLetterCode'
        iso_3n_code:
          $ref: '#/components/schemas/ThreeDigitCode'
        currencies:
          type: array
          items:
            type: object
            required:
            - name
            - iso_3a_code
            properties:
              name:
                $ref: '#/components/schemas/CurrencyName'
              iso_3a_code:
                $ref: '#/components/schemas/ThreeLetterCode'
              iso_3n_code:
                $ref: '#/components/schemas/ThreeDigitCode'
          description: A list of currencies used by the country
      example:
        name: ITALY
        iso_2a_code: IT
        iso_3a_code: ITA
        iso_3n_code: '380'
        currencies:
        - iso_3a_code: EUR
          iso_3n_code: '978'
          name: EURO
    StringMax255:
      description: Generic string definition, from 1 to 255 characters long
      type: string
      minLength: 1
      maxLength: 255
    CountryName:
      $ref: '#/components/schemas/StringMax70'
  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
  parameters:
    countryCode:
      name: country_code
      in: path
      required: true
      schema:
        type: string
        pattern: ^[A-Z]{2}$
      description: ISO 3166-1 alpha-2 country code
      example: DE
  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