openapi: 3.2.0
info:
  title: Clearbank Accounts API
  version: '1.0'
  description: 'Operations tagged Accounts across 2 of this provider''s published API definitions: clearbank-mccy-accounts-v2.json, clearbank-sterling-v4.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Accounts
paths:
  /mccy/v2/Accounts:
    post:
      tags:
      - Accounts
      summary: This endpoint is used to create a new real multi-currency account.
      parameters:
      - name: Authorization
        in: header
        description: Your API token, obtained from the ClearBank Portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request.
        required: true
        schema:
          type: string
      requestBody:
        description: Data to create the account.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccountRequest'
      responses:
        '201':
          description: Created
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          description: Bad Request
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Forbidden
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Client Error
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /v4/Accounts:
    post:
      tags:
      - Accounts
      summary: This endpoint is used to create a new FSCS-protected embedded banking account.
      description: If you want to create a cash ISA or savings account, use the POST /v1/isas or POST /v1/savings endpoints instead.
      operationId: V4InstitutionsByInstitutionIdAccountsPost
      parameters:
      - name: Authorization
        in: header
        description: Your API Token, obtained from the ClearBank Portal.
        required: true
        schema:
          type: string
      - name: DigitalSignature
        in: header
        description: Signed hash of the body of the request. The hash is signed by your private key.
        required: true
        schema:
          type: string
      - name: X-Request-Id
        in: header
        description: A unique identifier for the request; valid for 24 hours, max length 83.
        required: true
        schema:
          type: string
      requestBody:
        description: Information that is used to create a FSCS-protected current account.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClearBank.FI.API.Accounts.Versions.V4.Models.Binding.Accounts.CreateAccountRequest'
        required: true
        x-bodyName: request
      responses:
        '201':
          description: Created
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearBank.FI.API.Accounts.Versions.V4.Models.Response.Accounts.Account'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ClearBank.FI.API.Accounts.Versions.V4.Models.Response.Accounts.Account'
        '400':
          description: Bad Request
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
          content:
            application/json:
              schema:
                title: A validation problem object
                required:
                - errors
                type: object
                properties:
                  type:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A URI reference RFC3986 that identifies the problem type.
                    format: uri-reference
                  title:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see RFC7231, Section 3.4)
                  status:
                    maximum: 599
                    minimum: 100
                    type: integer
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
                  detail:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A human-readable explanation specific to this occurrence of the problem.
                  instance:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
                    format: uri-reference
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: Human-readable validation errors specific to this occurrence of the problem.
            application/problem+json:
              schema:
                title: A validation problem object
                required:
                - errors
                type: object
                properties:
                  type:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A URI reference RFC3986 that identifies the problem type.
                    format: uri-reference
                  title:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see RFC7231, Section 3.4)
                  status:
                    maximum: 599
                    minimum: 100
                    type: integer
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
                  detail:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A human-readable explanation specific to this occurrence of the problem.
                  instance:
                    type: string
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
                    format: uri-reference
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    description: Human-readable validation errors specific to this occurrence of the problem.
        '403':
          description: Forbidden
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
        '409':
          description: Conflict
          headers:
            X-Correlation-Id:
              description: A unique identifier which should be referenced in any issue with any API call.
              schema:
                type: string
components:
  schemas:
    AccountStatusReason:
      enum:
      - AccountHolderBankrupt
      - AccountHolderDeceased
      - AccountSwitched
      - CompanyNoLongerTrading
      - DissatisfiedCustomer
      - DuplicateAccount
      - FinancialCrime
      - FraudConfirmed
      - FraudFirstParty
      - FraudThirdParty
      - InternallyDormant
      - KYCRequired
      - LegallyDisputed
      - PotentialSanctionedIndividual
      - SanctionedIndividual
      - SuspectMoneyLaundering
      - TransactionDispute
      - Other
      type: string
      description: Reason for why the current status of the account is Closed or Suspended.
    AccountResponse:
      required:
      - currencies
      - id
      - identifiers
      - kind
      - label
      - name
      - owner
      - status
      - type
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the account held with ClearBank.
          format: uuid
          example: 98efba88-c43e-41c5-9d47-0938f2fe7192
        name:
          minLength: 1
          type: string
          description: Name of the account.
          example: Gen Seg Eco Bank
        label:
          type: string
          description: Friendly label for the account.
          example: Mid tier asset funds
        owner:
          type: string
          description: The name used to identify the legal owner of the account.
          example: Eco Bank
        kind:
          type: string
          description: The type of funds the account will hold.
          example: GeneralSegregated
          enum:
          - YourFunds
          - GeneralSegregated
          - DesignatedSegregated
          - GeneralClient
          - DesignatedClient
        currencies:
          type: array
          items:
            type: string
          description: Currencies supported by the account. This is the three-letter ISO currency code.
        productId:
          type:
          - string
          - 'null'
          description: The product identifier used to determine the behaviour of the account. Only applicable for FSCS accounts.
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        customerId:
          type:
          - string
          - 'null'
          description: Unique identifier for the customer that the account is associated with. Only applicable for FSCS accounts.
          format: uuid
          example: 190e5d1d-7016-4efe-9988-3ebfecb21192
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/AccountIdentifier'
          description: List of identifiers.
        status:
          type: string
          description: 'Current status of the account. Valid options include: Active, Suspended, Closed.'
          example: Active
        statusReason:
          $ref: '#/components/schemas/AccountStatusReason'
        statusInformation:
          type:
          - string
          - 'null'
          description: Additional information to support the specified status reason.
          example: Received documentation
        type:
          type: string
          description: The type of account.
          example: Customer
          enum:
          - Customer
          - Operating
      additionalProperties: false
    AccountIdentifier:
      required:
      - identifier
      - kind
      type: object
      properties:
        identifier:
          maxLength: 50
          minLength: 1
          type: string
          description: 'Unique account identifier value that corresponds to the specified account identifier kind. For example: when using kind ''Iban'', this should be the account''s IBAN value.'
        kind:
          minLength: 1
          type: string
          description: The kind of account identifier provided. This should always be 'Iban'.
          enum:
          - Iban
      additionalProperties: false
    CreateAccountRequest:
      required:
      - bankIdentifierCode
      - currencies
      - kind
      - label
      - owner
      - routingCode
      type: object
      properties:
        label:
          maxLength: 100
          minLength: 1
          pattern: ^[^<>;"]*$
          type: string
          description: Friendly label for the account.
          example: Mid tier asset funds
        owner:
          maxLength: 140
          minLength: 1
          pattern: ^[^<>;"]*$
          type: string
          description: The name used to identify the legal owner of the account.
          example: Eco Bank
        kind:
          type: string
          description: The type of funds the account will hold.
          example: GeneralSegregated
          enum:
          - YourFunds
          - GeneralSegregated
          - DesignatedSegregated
          - GeneralClient
          - DesignatedClient
        currencies:
          type: array
          items:
            type: string
          description: Currencies supported by the account. This is the three-letter ISO currency code.
        identifiers:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/AccountIdentifier'
          description: List of identifiers. If the account identifier of kind IBAN is not specified, it will be generated automatically.
        bankIdentifierCode:
          type:
          - string
          - 'null'
          description: The 8 or 11 character BIC under which the new account should be created. If using a UK BIC, a routing code will also be required.
          example: CLRBGB99
        routingCode:
          type:
          - string
          - 'null'
          description: Routing code for the new account. For example, 010203.
          example: '010203'
        productId:
          type:
          - string
          - 'null'
          description: The product identifier used to determine the behaviour of the account. Only applicable for FSCS accounts.
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        customerId:
          type:
          - string
          - 'null'
          description: Unique identifier for the customer that the account is associated with. Only applicable for FSCS accounts.
          format: uuid
          example: 725a5f09-595a-4db1-946a-8330d423da34
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    ClearBank.FI.API.Accounts.Versions.V4.Models.Response.Accounts.Account:
      required:
      - id
      - name
      - type
      - currency
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the current account.
          example: 01234567-89ab-cdef-0123-456789abcdef
        name:
          type: string
          description: The friendly name of the account.
          example: Current Account
        label:
          type: string
          description: The account holder label for the account.
          example: John Smith
        type:
          enum:
          - CACC
          type: string
          description: Specifies the type of the account. The only valid option is CACC.
          example: CACC
        currency:
          uniqueItems: false
          type: array
          items:
            enum:
            - AED
            - AFN
            - ALL
            - AMD
            - ANG
            - AOA
            - ARS
            - AUD
            - AWG
            - AZN
            - BAM
            - BBD
            - BDT
            - BGN
            - BHD
            - BIF
            - BMD
            - BND
            - BOB
            - BOV
            - BRL
            - BSD
            - BTN
            - BWP
            - BYN
            - BZD
            - CAD
            - CDF
            - CHE
            - CHF
            - CHW
            - CLF
            - CLP
            - CNY
            - COP
            - COU
            - CRC
            - CUC
            - CUP
            - CVE
            - CZK
            - DJF
            - DKK
            - DOP
            - DZD
            - EGP
            - ERN
            - ETB
            - EUR
            - FJD
            - FKP
            - GBP
            - GEL
            - GHS
            - GIP
            - GMD
            - GNF
            - GTQ
            - GYD
            - HKD
            - HNL
            - HRK
            - HTG
            - HUF
            - IDR
            - ILS
            - INR
            - IQD
            - IRR
            - ISK
            - JMD
            - JOD
            - JPY
            - KES
            - KGS
            - KHR
            - KMF
            - KPW
            - KRW
            - KWD
            - KYD
            - KZT
            - LAK
            - LBP
            - LKR
            - LRD
            - LSL
            - LYD
            - MAD
            - MDL
            - MGA
            - MKD
            - MMK
            - MNT
            - MOP
            - MRU
            - MUR
            - MVR
            - MWK
            - MXN
            - MXV
            - MYR
            - MZN
            - NAD
            - NGN
            - NIO
            - NOK
            - NPR
            - NZD
            - OMR
            - PAB
            - PEN
            - PGK
            - PHP
            - PKR
            - PLN
            - PYG
            - QAR
            - RON
            - RSD
            - RUB
            - RWF
            - SAR
            - SBD
            - SCR
            - SDG
            - SEK
            - SGD
            - SHP
            - SLL
            - SOS
            - SRD
            - SSP
            - STN
            - SVC
            - SYP
            - SZL
            - THB
            - TJS
            - TMT
            - TND
            - TOP
            - TRY
            - TTD
            - TWD
            - TZS
            - UAH
            - UGX
            - USD
            - USN
            - UYI
            - UYU
            - UZS
            - VEF
            - VND
            - VUV
            - WST
            - XAF
            - XAG
            - XAU
            - XBA
            - XBB
            - XBC
            - XBD
            - XCD
            - XDR
            - XOF
            - XPD
            - XPF
            - XPT
            - XSU
            - XTS
            - XUA
            - XXX
            - YER
            - ZAR
            - ZMW
            - ZWL
            type: string
          description: The currencies held in the account. This is the three-letter ISO currency code.
          example: GBP
        balances:
          uniqueItems: false
          type: array
          items:
            $ref: '#/components/schemas/ClearBank.FI.API.Accounts.Versions.V4.Models.Response.Accounts.Balance'
          description: Account balance in the given currency.
        productId:
          type: string
          description: The product identifier of the current account. It is used to determine the behaviour of the account.
          format: uuid
          example: 01234567-89ab-cdef-0123-456789abcdef
        customerId:
          type: string
          description: The unique identifier of the customer that holds the current account.
          format: uuid
          example: 01234567-89ab-cdef-0123-456789abcdef
        minimumBalance:
          type: number
          description: 'The minimum allowable balance of the account (example: -£1000).'
          format: double
          example: -500.55
        iban:
          type: string
          description: The IBAN identifier associated with the account.
          example: GB12CLBK01020312345678
        bban:
          type: string
          description: The BBAN identifier associated with the account.
          example: CLBK01020312345678
        upic:
          type: string
          description: The Universal Payment Identification Code (UPIC) associated with the account.
        cuid:
          type: string
          description: The CHIPS Universal Identifier associated with the account.
      description: Represents a summary of a given account.
    ClearBank.FI.API.Accounts.Versions.V4.Models.Binding.Accounts.CreateAccountRequest:
      required:
      - sortCode
      - productId
      - customerId
      type: object
      properties:
        owner:
          $ref: '#/components/schemas/ClearBank.FI.API.Accounts.Versions.V4.Models.Binding.Accounts.PartyIdentification'
        sortCode:
          pattern: ^\d{6}$
          type: string
          description: The sort code that the current account should be created under.
          example: '010203'
        productId:
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: The product identifier of the current account. It is used to determine the behaviour of the account.
          format: uuid
          example: 01234567-89ab-cdef-0123-456789abcdef
        customerId:
          pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$
          type: string
          description: The unique identifier of the customer that holds the current account.
          format: uuid
          example: 01234567-89ab-cdef-0123-456789abcdef
        minimumBalance:
          type: number
          description: 'The minimum allowable balance of the account (example: -£1000). Note that you must send a negative number to create an overdraft. This field can only be used if your organisation is an embedded banking client with an overdraft agreement in place; otherwise the request will be rejected.'
          format: double
          example: -500.55
      description: Information that is used to create a FSCS-protected current account.
    ClearBank.FI.API.Accounts.Versions.V4.Models.Binding.Accounts.PartyIdentification:
      type: object
      properties:
        name:
          maxLength: 140
          minLength: 0
          pattern: ^[^\|_\[\]<>^`~\\$]*$
          type: string
          description: Name for the owner of the current account.
          example: John Smith
      description: Set of elements used to identify a person or an organisation.
    ClearBank.FI.API.Accounts.Versions.V4.Models.Response.Accounts.Balance:
      required:
      - name
      - amount
      - currency
      - status
      type: object
      properties:
        name:
          type: string
          description: The name associated with the current account.
          example: Current Account
        amount:
          type: number
          description: The amount of funds in the account in a specific currency.
          format: double
          example: 54321.54
        currency:
          enum:
          - AED
          - AFN
          - ALL
          - AMD
          - ANG
          - AOA
          - ARS
          - AUD
          - AWG
          - AZN
          - BAM
          - BBD
          - BDT
          - BGN
          - BHD
          - BIF
          - BMD
          - BND
          - BOB
          - BOV
          - BRL
          - BSD
          - BTN
          - BWP
          - BYN
          - BZD
          - CAD
          - CDF
          - CHE
          - CHF
          - CHW
          - CLF
          - CLP
          - CNY
          - COP
          - COU
          - CRC
          - CUC
          - CUP
          - CVE
          - CZK
          - DJF
          - DKK
          - DOP
          - DZD
          - EGP
          - ERN
          - ETB
          - EUR
          - FJD
          - FKP
          - GBP
          - GEL
          - GHS
          - GIP
          - GMD
          - GNF
          - GTQ
          - GYD
          - HKD
          - HNL
          - HRK
          - HTG
          - HUF
          - IDR
          - ILS
          - INR
          - IQD
          - IRR
          - ISK
          - JMD
          - JOD
          - JPY
          - KES
          - KGS
          - KHR
          - KMF
          - KPW
          - KRW
          - KWD
          - KYD
          - KZT
          - LAK
          - LBP
          - LKR
          - LRD
          - LSL
          - LYD
          - MAD
          - MDL
          - MGA
          - MKD
          - MMK
          - MNT
          - MOP
          - MRU
          - MUR
          - MVR
          - MWK
          - MXN
          - MXV
          - MYR
          - MZN
          - NAD
          - NGN
          - NIO
          - NOK
          - NPR
          - NZD
          - OMR
          - PAB
          - PEN
          - PGK
          - PHP
          - PKR
          - PLN
          - PYG
          - QAR
          - RON
          - RSD
          - RUB
          - RWF
          - SAR
          - SBD
          - SCR
          - SDG
          - SEK
          - SGD
          - SHP
          - SLL
          - SOS
          - SRD
          - SSP
          - STN
          - SVC
          - SYP
          - SZL
          - THB
          - TJS
          - TMT
          - TND
          - TOP
          - TRY
          - TTD
          - TWD
          - TZS
          - UAH
          - UGX
          - USD
          - USN
          - UYI
          - UYU
          - UZS
          - VEF
          - VND
          - VUV
          - WST
          - XAF
          - XAG
          - XAU
          - XBA
          - XBB
          - XBC
          - XBD
          - XCD
          - XDR
          - XOF
          - XPD
          - XPF
          - XPT
          - XSU
          - XTS
          - XUA
          - XXX
          - YER
          - ZAR
          - ZMW
          - ZWL
          type: string
          description: Set to 'GBP' as other currencies are not supported.
          example: GBP
        status:
          enum:
          - CLBD
          - XPCD
          - OTHR
          - VALU
          type: string
          description: The type of balance being reported.
          example: VALU
      description: A summary of the balance of an account, in a specific currency.
x-refined-from:
- clearbank-mccy-accounts-v2.json
- clearbank-sterling-v4.json