Logo
Swift API Sandbox Collections API Documentation

SwiftRef API

Number of APIs: 33


One of SWIFT's latest delivery channels for SWIFTRef reference data are Application Programming Interfaces (APIs). APIs offer financial institutions, corporates and third party service providers an automated data look-up service for real-time identification and validation of critical payments reference data within the SWIFTRef utility.

v4.0.0 Release notes

  • HTTP request header Accept now used for the customer expected format (JSON/XML):
    • it should only be application/json or application/xml;
    • if an unexpected accept header is received, an error 406 is returned. If not sent, the request is accepted and the default (JSON) will be applied.
  • Errors - all the V4 APIs return the error in the same format:
    • a collection, whose structure is [ {errorObject1}, {errorObject2}, ... ];
    • more_info error attribute became optional.
  • All the APIs within the OpenAPI contract have the same version. The version corresponds to the major version of the OpenAPI contract (OpenAPI contract 4.0.0 only contain V4 APIs).
  • Session cookie removed.
  • Header API-Status (API verbose) removed.
  • Response customization (EOL, colons) removed:
    • JSON responses are not returned pretty-printed, but raw.

  • OpenAPI changes

    • standardizations as per Swagger HUB rules
    • RegExp validations for each input field added
    • output format constraints added
    • standardized V4 version for all the APIs
    • 8 new endpoints added:
    • Search for PMI participants: GET /v4/pmis/participants
    • Get PMI participant details: GET /v4/pmis/participants/{participant_record_id}
    • Get PMI structure: GET /v4/pmis/{service_id}/structure
    • Get PMI details: GET /v4/pmis/{service_id}
    • Search for PMI: GET /v4/pmis
    • Get Connected BIC: GET /v4/bics/{bic}/connected_bic
    • Get BBAN elements of an IBAN (IBAN constructor metadata): GET /v4/bbans/elements
    • IBAN constructor (build IBAN): GET /v4/ibans
    • 7 existing endpoints updated:
    • Get SSIs for a BIC: GET /v4/bics/{bic}/connected_bic

    For a given BIC and a given currency code, and optionally an asset category, you can retrieve the Standing Settlement Instructions (SSIs). One or more SSIs can be returned.

    The V4 is based on the SSI Plus V3 directory. The v1.6 was based on SSI Plus V2 directory. Because the structure of SSI Plus V3 differs from the SSI Plus V2, there are several changes in the parameters: * Some request parameters changed name: * currency_code changed to iso_currency_code * ssi_category changed to asset_category * The asset category covers now all asset categories listed in the SSI Plus V3 directory. * Many new response attributes * Check validity of an IBAN (SEPA-only option added): GET /v4/ibans/{iban}/validity

    You can check whether an IBAN is valid, that is its country code, structure, length, and checksum are valid. It also checks that the bank ID exists and that it is allowed for use in the IBANs. If the bank ID is not allowed, then it is listed in the Exclusion List. This list contains bank IDs that must not be used in IBANs.

    This validity call allows for very fast, low overhead checking of the validity of an IBAN. With the new optional request parameter sepa_only, you can validate a SEPA IBAN. * One new request parameter added: sepa_only * Get details for a BIC: GET /v4/bics/{bic}

    For a given BIC, you can retrieve the details of that BIC, that is the bank name or business name, and the address.

    The V4 features ISO 20022-compliant attributes (see https://www.swift.com/resource/structured-ordering-and-beneficiary-customer-data-payments-1). * Get details for a National ID: GET /v4/national_ids/{national_id}

    For a given National ID, you can retrieve the details of that National ID, that is the bank name or business name, and the address. You must provide either a country code, or an indication to which scheme the National ID belongs.

    You can also receive the National ID's data elements (such as the name and address in the local language instead of in English), if you add the URL extension &only_local_language=true. However, the local language elements are available only for a subset of all National IDs.

    The V4 features ISO 20022-compliant attributes (see https://www.swift.com/resource/structured-ordering-and-beneficiary-customer-data-payments-1); all available national ID schemes are now returned (idtype, nationalidtype, isoclctype). * Validate National ID: `GET /v4/nationalids/{national_id}/validity`

    All available national ID schemes are available as input and returned to output (idtype, nationalidtype, isoclctype). * Get BICs of a National ID: `GET /v4/nationalids/{national_id}/bics`

    All available national ID schemes are available as input (idtype, nationalidtype, isoclctype). * Get National IDs of a BIC: `GET /v4/bics/{bic}/nationalids`

    All available national ID schemes are now returned (idtype, nationalidtype, isoclc_type); AN and FN type attribute, previously used to flag items as Alternative National ID Type or Foreign National ID Type, are not returned anymore.

Contact Support: Name: Standards & Developer Hub Email: developer-support@swift.com


1. Authorization - Refresh Token

POST https://sandbox.swift.com/oauth2/v1/token


2. Success-ibans-{iban} - Get details for an IBAN.

GET {{baseUrl}}/ibans/:iban

For a given IBAN, you can obtain the components of the IBAN.


3. Success-ibans-{iban} - Check validity of an IBAN, with SEPA-only option.

GET {{baseUrl}}/ibans/:iban/validity?sepa_only=true

You can check whether an IBAN is valid, by restricting validation to SEPA countries.


4. Success-ibans-{iban} - Get the BIC for an IBAN.

GET {{baseUrl}}/ibans/:iban/bic

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.


5. Success-ibans - IBAN constructor.

GET {{baseUrl}}/ibans?country_code=BE&bban=363030309813

Build a valid IBAN from BBAN elements (e.g. bank code, branch code, account number). Required BBAN elements depend on the country.


6. Success-bics/{bic} - Get details of a BIC.

GET {{baseUrl}}/bics/:bic

For a given BIC, you can retrieve the details of that BIC, that is the bank name or business name, and the address and the SWIFT service details.


7. Success-bics/{bic} - Check validity of a BIC.

GET {{baseUrl}}/bics/:bic/validity?effective_date=2019-07-23

You can check whether a BIC is correct and valid, that is whether it is published in the BIC Directory; optionally, you can check whether a BIC was valid at a particular date in the past.


8. Success-bics/{bic} - Get the LEI for a BIC.

GET {{baseUrl}}/bics/:bic/lei

For a given BIC (Business Identifier Code), you can retrieve the LEI (Legal Entity Identifier) of that BIC.


9. Success-bics/{bic} - Get National IDs for a BIC.

GET {{baseUrl}}/bics/:bic/national_ids

For a given BIC, you can retrieve the National IDs of that BIC.


10. Success-bics/{bic} - Validate SEPA reachability of a BIC.

GET {{baseUrl}}/bics/:bic/reachability?sepa_scheme=SDD

For a given BIC and SEPA payment scheme, you can validate that it can be reached for SEPA payments and return the SEPA channel CSM (Clearing and Settlement System) through which the bank owning the BIC can be reached; the response also returns the adherence BIC that signed the adherence agreement with the EPC and the intermediary institution's BIC (if applicable and available).


11. Success-bics/{bic} - Get SSIs for a BIC.

GET {{baseUrl}}/bics/:bic/ssis?iso_currency_code=EUR&asset_category=COPA

For a given BIC, you can retrieve the Standing Settlement Instructions (SSIs) for that BIC, for a given currency, and (optionally) an asset category.


12. Success-bics/{bic} - Get connected BIC.

GET {{baseUrl}}/bics/:bic/connected_bic

For a given BIC, retrieve the related connected BIC (or SWIFT BIC), which is a BIC connected to the SWIFT network, therefore usable in the header of a SWIFT message. If available, it is a BIC of the same institution, otherwise it's the correspondent through which the input BIC connects.


13. Success-bbans - Get the IBAN from a BBAN.

GET {{baseUrl}}/bbans/:bban/iban?country_code=BE

For a given Basic Bank Account Number (BBAN), you can retrieve the corresponding IBAN; you must also provide a country code.


14. Success-bbans - Get BBAN elements of an IBAN country.

GET {{baseUrl}}/bbans/elements?country_code=BE

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.


15. Success-leis/{lei} - Get details of a LEI.

GET {{baseUrl}}/leis/:lei

For a given LEI, you can retrieve the details of that LEI.


16. Success-leis/{lei} - Get the BIC for an LEI.

GET {{baseUrl}}/leis/:lei/bic

For a given LEI, you can retrieve the BIC of that LEI.


17. Success-leis/{lei} - Check validity of a LEI.

GET {{baseUrl}}/leis/:lei/validity

You can check whether a LEI is formally correct and exists.


18. Success-national ids/{national id} - Get details of a National ID.

GET {{baseUrl}}/national_ids/:national_id?country_code=NZ

For a given National ID, you can retrieve the details of that National ID, that is the bank name or business name, and the address. You must provide either a country code, or an indication to which scheme the National ID belongs.


19. Success-national ids/{national id} - Check the Validity of a National ID.

GET {{baseUrl}}/national_ids/:national_id/validity?country_code=NZ

With this API call, you can check whether a National ID format is correct and the value exists in SWIFT's list of National IDs; you need to provide the National ID, and either a country code, or an indication to which scheme this National ID belongs.


20. Success-national ids/{national id} - Get BICs of a National ID.

GET {{baseUrl}}/national_ids/:national_id/bics?country_code=NZ

For a given National ID, you can retrieve the BIC or the BICs of that National ID; you need to provide the National ID, and either a country code, or an indication to which scheme this National ID belongs.


21. Success-country codes/{country code} - Get details of a country code.

GET {{baseUrl}}/country_codes/:country_code

For a given country code, you can retrieve the details of that country code, that is the name, other codes and official currencies.


22. Success-country codes/{country code} - Check validity of a country code.

GET {{baseUrl}}/country_codes/:country_code/validity

You can check whether a country code is correct and valid.


23. Success-currency codes/{currency code} - Get details of a currency code.

GET {{baseUrl}}/currency_codes/:currency_code

For a given currency code, you can retrieve the details of that currency code, that is the name, other codes, the fractional digits and the list of countries where the currency is used.


24. Success-currency codes/{currency code} - Check validity of a currency code.

GET {{baseUrl}}/currency_codes/:currency_code/validity

You can check whether a currency code is correct and valid.


25. Success-currency codes/{currency code} - Check validity of a currency amount.

GET {{baseUrl}}/currency_codes/:currency_code/amount_validity?amount=12,34

You can check whether an amount is valid for a specific currency.


26. Success-pmis-participants - Search for PMI participants.

GET {{baseUrl}}/pmis/participants?service_id_substring=STEP1&participant_id_substring=GEB&participant_name_substring=BNP&country_code=BE&offset=20&limit=20

Get a list of PMI (Payment Market Infrastructure) participants matching the input parameters.


27. Success-pmis-participants - Get PMI participant details.

GET {{baseUrl}}/pmis/participants/:participant_record_id

For a given participant record ID, you can retrieve all details of that PMI participant, as reported within REACHPLUS flatfile.


28. Success-pmis-{service id} - Get PMI details.

GET {{baseUrl}}/pmis/:service_id

Get Payment Market Infrastructure details for the given service ID.


29. Success-pmis-{service id} - Get PMI participant structure.

GET {{baseUrl}}/pmis/:service_id/structure

For the given Payment Market Infrastructure service ID, get the participant record structure as described by flatfile REACHPLUSSTRUCTURE.


30. Success-pmis - Search for Payment Market Infrastructures.

GET {{baseUrl}}/pmis?currency_code=EUR&country_code=DE

Get a list of Payment Market Infrastructures matching the input parameters.


31. Success - Get the BIC for an IBAN national ID.

GET {{baseUrl}}/iban_national_ids/:iban_national_id/bic?country_code=IT

For a given IBAN national ID, you can retrieve the BIC of the institution that services the IBAN.


32. Success - Check validity of account number formats, including IBANs.

GET {{baseUrl}}/account_numbers/:account_number/validity?country_code=IT&usage=retail&national_id=0542811101

Check validity of account number formats, including IBANs, issued in almost any country in the world.


33. Teardown - Revoke Token

POST https://sandbox.swift.com/oauth2/v1/revoke


  • FAQs

  • More

    Developer Website

    Claim this page

    Report this page

ENDPOINTS