OpenAPI Specification
openapi: 3.1.0
info:
title: SWIFT SwiftRef Account Numbers BICs API
description: The SWIFT SwiftRef API provides automated real-time lookup and validation of payments reference data. Supports validation and retrieval of BICs, IBANs, LEIs, National IDs, country codes, currency codes, and account numbers. Enables financial institutions, corporates, and PSPs to achieve greater straight-through processing rates by validating identifiers before payment execution. Data is updated daily from authoritative sources.
version: 2.0.0
contact:
name: SWIFT Developer Support
email: developer-support@swift.com
url: https://developer.swift.com
termsOfService: https://developer.swift.com/terms
servers:
- url: https://api.swift.com/swiftrefdata
description: SWIFT SwiftRef Production API
- url: https://sandbox.swift.com/swiftrefdata
description: SWIFT SwiftRef Sandbox
security:
- OAuth2: []
tags:
- name: BICs
description: BIC (Bank Identifier Code) lookup and validation
paths:
/v2/bics/{bic}:
get:
operationId: getBic
summary: Get BIC Details
description: Returns detailed information about a BIC (Bank Identifier Code) including institution name, address, and connectivity status.
tags:
- BICs
parameters:
- $ref: '#/components/parameters/bic'
responses:
'200':
description: BIC details
content:
application/json:
schema:
$ref: '#/components/schemas/BicDetails'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/v2/bics/{bic}/validity:
get:
operationId: validateBic
summary: Validate BIC
description: Checks the validity of a BIC code, confirming it is a registered and active BIC in the SWIFT network.
tags:
- BICs
parameters:
- $ref: '#/components/parameters/bic'
responses:
'200':
description: BIC validity result
content:
application/json:
schema:
$ref: '#/components/schemas/ValidityResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/v2/bics/{bic}/lei:
get:
operationId: getBicLei
summary: Get LEI for BIC
description: Returns the Legal Entity Identifier (LEI) associated with a BIC.
tags:
- BICs
parameters:
- $ref: '#/components/parameters/bic'
responses:
'200':
description: LEI for the BIC
content:
application/json:
schema:
type: object
properties:
lei:
type: string
description: Legal Entity Identifier
'404':
$ref: '#/components/responses/NotFound'
/v2/bics/{bic}/national_ids:
get:
operationId: getBicNationalIds
summary: Get National IDs for BIC
description: Returns all National IDs associated with a BIC.
tags:
- BICs
parameters:
- $ref: '#/components/parameters/bic'
responses:
'200':
description: National IDs for the BIC
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/NationalId'
'404':
$ref: '#/components/responses/NotFound'
/v2/bics/{bic}/reachability:
get:
operationId: getBicSepaReachability
summary: Validate SEPA Reachability
description: Validates whether a BIC is reachable via SEPA (Single Euro Payments Area) credit transfer or direct debit schemes.
tags:
- BICs
parameters:
- $ref: '#/components/parameters/bic'
responses:
'200':
description: SEPA reachability status
content:
application/json:
schema:
$ref: '#/components/schemas/ReachabilityResult'
'404':
$ref: '#/components/responses/NotFound'
/v2/bics/{bic}/ssis:
get:
operationId: getBicSsis
summary: Get SSIs for BIC
description: Returns Standard Settlement Instructions (SSIs) associated with a BIC.
tags:
- BICs
parameters:
- $ref: '#/components/parameters/bic'
responses:
'200':
description: SSIs for the BIC
content:
application/json:
schema:
type: array
items:
type: object
'404':
$ref: '#/components/responses/NotFound'
components:
parameters:
bic:
name: bic
in: path
required: true
schema:
type: string
pattern: ^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$
description: 8 or 11 character BIC (Bank Identifier Code)
example: DEUTDEDB
responses:
NotFound:
description: Identifier not found in reference data
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
Unauthorized:
description: Unauthorized - invalid or expired OAuth token
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
BadRequest:
description: Bad request - invalid identifier format
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
schemas:
BicDetails:
type: object
properties:
bic:
type: string
description: Bank Identifier Code
institutionName:
type: string
description: Name of the financial institution
countryCode:
type: string
description: ISO 3166-1 country code
city:
type: string
description: City where the institution is located
address:
type: string
description: Institution address
status:
type: string
description: BIC status (active, passive, etc.)
connectedToBIC:
type: boolean
description: Whether the BIC is connected to SWIFT network
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
NationalId:
type: object
properties:
nationalId:
type: string
description: National clearing code
type:
type: string
description: Type of national ID (ABA, CHIPS, SORT, etc.)
countryCode:
type: string
description: Country code
ReachabilityResult:
type: object
properties:
sepaCtReachable:
type: boolean
description: Whether BIC is reachable for SEPA Credit Transfer
sepaDirectDebitReachable:
type: boolean
description: Whether BIC is reachable for SEPA Direct Debit
sepaInstantReachable:
type: boolean
description: Whether BIC is reachable for SEPA Instant payments
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
externalDocs:
description: SWIFT SwiftRef API Documentation
url: https://developer.swift.com/apis/swiftref-api