openapi: 3.0.3
info:
  title: Spec
  x-displayName: API Spec
  version: '4.1.0'
  description: |-
    The Wych Data Recipient API allows you to connect customer-permissioned data from supported banks and data holders into your application.

    This API is designed for Recipient and open banking use cases such as onboarding, account aggregation, transaction retrieval, analysis and customer-permissioned data sharing.

    ## What you can do with this API

    Using this API, you can:

    - authenticate your application
    - create or locate an application user
    - launch and manage consent journeys
    - retrieve customer connections and consent state
    - access accounts, balances, transactions and related payment details
    - work with supported data holders and provider configurations

    ## How the API works

    The Wych Recipient API typically follows this flow:

    1. authenticate your application using your API key and client credentials
    2. create or find the user in your application context
    3. create or launch a consent journey
    4. wait for the customer to complete consent with their institution
    5. retrieve customer data using the active connection

    ## Authentication

    Protected API requests use:

    - `x-api-key`
    - `Authorization: Bearer <token>`

    Depending on the endpoint, you may use either:

    - an application-level token
    - a user-context token for customer-specific data access

    ## Main API sections

    ### Core

    Core endpoints support application authentication, user management, consent and connection management, and data holder discovery.

    ### Customer Data

    Customer Data endpoints provide access to account, balance, transaction and related financial data once consent is active.

    ### Payment Details

    Payment Details endpoints provide access to payees, scheduled payments and direct debit information where available.

    ## Before you start

    Before calling this API, make sure you have:

    - a configured Partner profile
    - a registered application
    - valid client credentials
    - a valid API key
    - an appropriate consent flow configured for your use case

    ## Getting started

    For a typical integration, start with these endpoints:

    - OpenID configuration
    - Generate a client auth token
    - Create or find a user
    - Create a connection
    - Authorize a connection
    - Get all accounts
    - Get account transactions

    ## Related documentation

    For portal setup, consent guidance and integration walkthroughs, refer to the Wych Recipient quick start and guides.
  contact:
    name: Customer Support
    email: support@wych.it

  license:
    name: 'Wych Holdings Limited, All rights reserved'
    url: 'https://www.wych.io/'

  termsOfService: 'https://www.wych.io/terms-conditions'

servers:
  - url: 'https://api.wych.io/access/v4'

externalDocs:
  url: 'https://docs.wych.io'

tags:
  - name: auth-token
    description: Authenticate for access to the Wych platform
    x-displayName: Authentication
  - name: app-user
    description: Information for system and CDR user data.
    x-displayName: Users
  - name: bank-account
    x-displayName: Accounts
    description: Accounts information for the bank CDR data.
  - name: bank-balance
    x-displayName: Balances
    description: Balance information for the bank CDR data.
  - name: bank-transaction
    x-displayName: Transactions
    description: Transaction information for the bank CDR user.
  - name: bank-payee
    x-displayName: Payees
    description: Information about saved Payees for this account.
  - name: bank-scheduled-payments
    x-displayName: Scheduled Payments
    description: Scheduled payment information
  - name: bank-account-product
    x-displayName: Account product
    description: Information about the accounts product.
  - name: bank-direct-debits
    x-displayName: Direct Debits
    description: Information about direct debits associated with this account.
  - name: connection
    x-displayName: Consents
    description: Create, authorise and manage customer connections and consent with data holders.
  - name: data-holder
    x-displayName: Data Holders
    description: Register and manage CDR Data Holders.

x-tagGroups:
  - name: Core
    tags:
      - auth-token
      - app-user
      - user-auth
      - connection
      - data-holder
    
  - name: Customer Data
    tags:
    - bank-account
    - bank-account-product
    - bank-balance
    - bank-other
    - bank-product
    - bank-transaction
    - energy-account
    - energy-balance
    - energy-plans

  - name: Payment Details
    tags:
    - bank-payee
    - bank-direct-debits
    - bank-scheduled-payments

paths:
  '/realms/{app}/.well-known/openid-configuration':
    servers:
      - url: https://login.wych.app
    parameters:
    - name: app
      in: path
      required: true
      schema:
        type: string
      description: The name of your app
    get:
      description: >-
        Returns the OpenID Connect discovery metadata for the application, including the issuer, token, authorisation, user information and JWKS endpoints.
      servers:
        - url: 'https://login.wych.app'
      operationId: openid-configuration
      security: []
      summary: Get OpenID configuration
      tags:
        - auth-token
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  issuer:
                    type: string
                  authorization_endpoint:
                    type: string
                  token_endpoint:
                    type: string
                  introspection_endpoint:
                    type: string
                  userinfo_endpoint:
                    type: string
                  end_session_endpoint:
                    type: string
                  jwks_uri:
                    type: string
                  check_session_iframe:
                    type: string
                  grant_types_supported:
                    type: array
                    enum:
                      - authorization_code
                      - refresh_token
                      - client_credentials
                    uniqueItems: true
                    items: {}
              example:
                issuer: 'https://login.wych.app/realms/{app}'
                authorization_endpoint: >-
                  https://login.wych.app/realms/{app}/protocol/openid-connect/auth
                token_endpoint: >-
                  https://login.wych.app/realms/{app}/protocol/openid-connect/token
                introspection_endpoint: >-
                  https://login.wych.app/realms/{app}/protocol/openid-connect/token/introspect
                userinfo_endpoint: >-
                  https://login.wych.app/realms/{app}/protocol/openid-connect/userinfo
                end_session_endpoint: >-
                  https://login.wych.app/realms/{app}/protocol/openid-connect/logout
                jwks_uri: >-
                  https://login.wych.app/realms/{app}/protocol/openid-connect/certs
                grant_types_supported:
                  - authorization_code refresh_token client_credentials
  '/realms/{app}/protocol/openid-connect/token':
    servers:
      - url: https://login.wych.app
    parameters:
    - name: app
      in: path
      required: true
      schema:
        type: string
      description: The name of your app
    post:
      description: >-
        Authenticates the application using its client credentials and returns an access token for application-level API operations.
      operationId: getClientAuthToken
      summary: Generate client token
      tags:
        - auth-token
      security:
        - apiKey: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - client_id
                - client_secret
                - grant_type
              properties:
                client_id:
                  type: string
                client_secret:
                  type: string
                grant_type:
                  type: string
            example:
              client_id: client_123456789
              client_secret: supxxxxxxxxret
              grant_type: client_credentials
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                required:
                  - access_token
                  - expires_in
                  - refresh_expires_in
                  - token_type
                  - not-before-policy
                  - scope
                properties:
                  access_token:
                    type: string
                  expires_in:
                    type: integer
                  refresh_expires_in:
                    type: integer
                  token_type:
                    type: string
                  not-before-policy:
                    type: integer
                  scope:
                    type: string
              example:
                access_token: eyJhbGc...7Zkg
                expires_in: 900
                refresh_expires_in: 0
                token_type: Bearer
                not-before-policy: 0
                scope: 'EXECUTE:TOKEN_EXCHANGE READ:APP_USERS'
        '400':
          description: >-
            Bad Request

            The minimum header and/or parameter requirement for this request has
            not been met.
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - error_description
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
              example:
                error: unsupported_grant_type
                error_description: Unsupported grant_type
        '401':
          description: |-
            Unauthorised
            The minimum authorisation for the request has been met. 
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - error_description
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
              example:
                error: unauthorized_client
                error_description: Invalid client or Invalid client credentials
  '/user/{userId}/token':
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the user
    get:
      summary: Get user token
      description: >-
        Exchanges the authenticated client context for a user access token used to call customer-specific API endpoints.
      operationId: retrieveAppUserToken
      security:
        - apiKey: []
          clientToken:
            - 'EXECUTE:TOKEN_EXCHANGE'
      tags:
        - auth-token
      responses:
        '200':
          description: |-
            Found
            The user token if found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/user/{userId}/link':
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the user
    get:
      description: >-
        Generates a magic login link for the specified application user.
      operationId: createAppUserMagicLink
      security:
        - apiKey: []
          clientToken:
            - 'EXECUTE:TOKEN_EXCHANGE'
      summary: Get magic login link
      tags:
        - auth-token
      responses:
        '200':
          description: |-
            Found
            The user token if found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MagicLink'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with a user
    get:
      description: >-
        Retrieves account details for the specified account, including its type, status, account numbers, product information and lending details where available.
      operationId: getAccount
      security:
        - apiKey: []
          userToken:
            - 'READ:ACCOUNT'
      summary: Get account
      tags:
        - bank-account
      responses:
        '200':
          description: |-
            Found
            The account details if account is found for accountId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/balance':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with the subscriber
    get:
      description: >-
        Retrieves the current balance information for the specified account.
      operationId: getBalance
      security:
        - apiKey: []
          userToken:
            - 'READ:BALANCE'
      summary: Get account balance
      tags:
        - bank-balance
      responses:
        '200':
          description: The balance for the given account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/direct-debits':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with the subscriber
    get:
      description: Get direct debits for bank account
      operationId: getDirectDebits
      security:
        - apiKey: []
          userToken:
            - 'READ:DIRECTDEBIT'
      summary: Get direct debits
      tags:
        - bank-direct-debits
      responses:
        '200':
          description: The direct debits for the given account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DirectDebits'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/number/{accountNumberId}':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with the subscriber
      - name: accountNumberId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account number
    get:
      description: >-
        Retrieves a specific account number associated with the account.
      operationId: getAccountNumber
      security:
        - apiKey: []
          userToken:
            - 'READ:ACCOUNT'
      summary: Get account number
      tags:
        - bank-account
      responses:
        '200':
          description: The account number associated with the accountNumberId passed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNumber'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/numbers':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with the subscriber
    get:
      description: >-
        Retrieves the account numbers associated with the specified account.
      operationId: getAccountNumbers
      security:
        - apiKey: []
          userToken:
            - 'READ:ACCOUNT'
      summary: List account numbers
      tags:
        - bank-account
      responses:
        '200':
          description: List of the account numbers of the associated account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountNumbers'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/payee/{payeeId}':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with the subscriber
      - name: payeeId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the payeeId
    get:
      description: Get payee for the associated account
      operationId: getPayee
      security:
        - apiKey: []
          userToken:
            - 'READ:PAYEE'
      summary: Get a payee
      tags:
        - bank-payee
      responses:
        '200':
          description: The payee associated with the payeeId passed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payee'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/payees':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with the subscriber
    get:
      description: Get all Payees for account id
      operationId: getPayees
      security:
        - apiKey: []
          userToken:
            - 'READ:PAYEE'
      summary: Get account payees
      tags:
        - bank-payee
      responses:
        '200':
          description: List of the payees associated with the account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payees'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/product':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with a user
    get:
      description: Retrieves product information associated with the specified account.
      operationId: getAccountProduct
      security:
        - apiKey: []
          userToken:
            - 'READ:ACCOUNT_PRODUCT'
      summary: Get account product
      tags:
        - bank-account-product
      responses:
        '200':
          description: |-
            Found
            The account details if account is found for accountId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/scheduled-payments':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with a user
    get:
      description: Get scheduled payments by account id
      operationId: getAccountScheduledPayments
      security:
        - apiKey: []
          userToken:
            - 'READ:SCHEDULED_PAYMENT'
      summary: Get an account's scheduled payment details
      tags:
        - bank-scheduled-payments
      responses:
        '200':
          description: |-
            Found
            The account details if account is found for accountId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduledPayments'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/account/{accountId}/transactions':
    parameters:
      - name: accountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the account associated with the subscriber
    get:
      description: Get transactions for user account
      operationId: getTransactions
      parameters:
        - name: start
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2018-09-15T15:53:00Z'
          description: ISO 8601 - the start date of the transaction range
        - name: end
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2018-09-15T15:53:00Z'
          description: ISO 8601  the end date of the transaction range
        - name: min
          in: query
          required: false
          schema:
            type: number
          description: The smallest amount to return
        - name: max
          in: query
          required: false
          schema:
            type: number
          description: The largest amount to return
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: The page number of results to return
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
          description: The number of results to return per page
      security:
        - apiKey: []
          userToken:
            - 'READ:TRANSACTION'
      summary: Get account transactions
      tags:
        - bank-transaction
      responses:
        '200':
          description: A list of transactions associated with a users account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transactions'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /accounts:
    get:
      parameters:
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: Category filter
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AccountStatus'
          description: Status filter
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: The page number of results to return
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
          description: The number of results to return per page
      description: >-
        Retrieves the user's accounts. Results can be filtered by account category and status and support pagination.
      operationId: getAccounts
      security:
        - apiKey: []
          userToken:
            - 'READ:ACCOUNT'
      summary: List accounts
      tags:
        - bank-account
      responses:
        '200':
          description: |-
            Found 
            List of the account details if accounts are found for the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Accounts'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /balance:
    get:
      description: >-
        Retrieves balances for the user's accounts. Results can be filtered by account, category, status and date range.
      operationId: getBalances
      parameters:
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: Category filter
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AccountStatus'
          description: Status filter
        - name: accountId
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uuid
          description: Account filter
        - name: from
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2026-01-15T15:53:00Z'
          description: UTC timestamp in ISO 8601 format
        - name: to
          in: query
          required: false
          schema:
            type: string
            format: date-time
            example: '2026-02-15T15:53:00Z'
          description: UTC timestamp in ISO 8601 format
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: The page number of results to return
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
          description: The number of results to return per page
      security:
        - apiKey: []
          userToken:
            - 'READ:BALANCE'
      summary: List balances
      tags:
        - bank-balance
      responses:
        '200':
          description: |-
            Found\ 
            List of the account balances if accounts are found for the user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balances'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /connection:
    post:
      description: >-
        Initialises a connection between the user and a data holder. The connection must be authorised before 
        customer-permissioned data can be accessed.
      operationId: createConnection
      security:
        - apiKey: []
          userToken:
            - 'CREATE:CONNECTION'
      summary: Create a connection
      requestBody:
        $ref: '#/components/requestBodies/Connection'
      tags:
        - connection
      responses:
        '201':
          $ref: '#/components/responses/201'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/connection/{connectionId}':
    parameters:
      - name: connectionId
        in: path
        required: true
        description: The id of the connection
        schema:
          type: string
          format: UUID
    get:
      description: >-
        Retrieves a connection and its current details, including the associated user, data holder, consent scopes and connection status.
      operationId: getConnection
      security:
        - apiKey: []
          userToken:
            - 'READ:CONNECTION'
      summary: Get a connection
      tags:
        - connection
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/connection/{connectionId}/authorize':
    parameters:
      - name: connectionId
        in: path
        required: true
        description: The id of the connection
        schema:
          type: string
          format: UUID
    post:
      description: >-
        Starts the customer consent journey for the connection and returns the URI used to redirect the customer to the data holder for authorisation.
      operationId: authorizeConnection
      security:
        - apiKey: []
          userToken:
            - 'CREATE:CONNECTION'
      summary: Authorise a connection
      tags:
        - connection
      responses:
        '200':
          description: Redirect to the authorization provider
          content:
            application/json:
              schema:
                type: object
                properties:
                  uri:
                    type: string
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/connection/{connectionId}/amend':
    parameters:
    - name: connectionId
      in: path
      required: true
      description: The id of the connection
      schema:
        type: string
        format: UUID
    put:
      description: >-
        Allows the API requester to amend the scopes or permissions associated with an existing connection. 
        Returns the URI used to redirect the customer to the data holder to review and reconsent to the updated permissions.
      operationId: amendConnection
      security:
      - apiKey: []
        userToken:
            - 'CREATE:CONNECTION'
      summary: Amend a connection
      x-backend: connection
      tags:
        - connection
      responses:
        '200':
          description: Redirect to the authorization provider
          content:
            application/json:
              schema:
                type: object
                properties:
                  uri:
                    type: string
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/connection/{connectionId}/disconnect':
    parameters:
      - name: connectionId
        description: id of the connection
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      description: >-
        Revokes the consent associated with the connection and disconnects the user from the data holder.
      operationId: revokeConnection
      security:
        - apiKey: []
        - userToken:
            - 'DELETE:CONNECTION'
      summary: Revoke a connection
      tags:
        - connection
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/connection/{connectionId}/state':
    parameters:
      - name: connectionId
        description: id of the connection
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      description: >-
        Retrieves the current connection status together with available connection and data extraction timestamps and state information.
      operationId: readCurrentConnectionState
      security:
        - apiKey: []
        - userToken:
            - 'READ:CONNECTION'
      summary: Get connection state
      tags:
        - connection
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionState'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /connection/{connectionId}/refresh:
    parameters:
      - name: connectionId
        in: path
        required: true
        description: The id of the connection
        schema:
          type: string
          format: UUID
      - name: x-fapi-customer-ip-address
        in: header
        required: false
        description: The IP address of the customer
        schema:
          type: string
    post:
      description: |-
        Requests a new extraction of customer-permissioned data for an existing connection. 
        The request can specify the data types and number of days to refresh.
      operationId: triggerConnectionDataRefresh
      security:
        - apiKey: []
          userToken: 
            - 'READ:CONNECTION'
      summary: Refresh connection data
      requestBody:
        $ref: '#/components/requestBodies/ConnectionDataRefresh'
      x-backend: connection
      tags:
        - connection
      responses:
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /connections:
    get:
      description: |-
        Retrieves the user's connections. Results can be filtered by data holder or connection status.
      operationId: getConnections
      parameters:
        - name: dataHolderId
          in: query
          required: false
          description: The id of the data holder
          schema:
            type: string
            format: UUID
        - name: status
          in: query
          description: Filter for the connection status
          schema:
            $ref: '#/components/schemas/ConnectionStateEnum'
      security:
        - apiKey: []
          userToken:
            - 'READ:CONNECTIONS'
      summary: List connections
      tags:
        - connection
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connections'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/connection/{connectionId}/extractions':
    parameters:
      - name: connectionId
        description: id of the connection
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      description: >-
        Retrieves the extraction history for a connection, allowing you to inspect the status of data retrieval activity.
      operationId: readConnectionExtractions
      security:
        - apiKey: []
        - userToken:
            - 'READ:CONNECTION'
      summary: List connection extractions
      tags:
        - connection
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/ConnectionState'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/data-holders':
    get:
      description: >-
        Retrieves available data holders grouped by provider. Results can be filtered by country using an ISO 3166 country code.
      operationId: listDataholders
      parameters:
        - name: country
          in: query
          required: false
          description: The ISO 3166 of the country
          schema:
            type: string
      security:
        - apiKey: []
          userToken:
            - 'READ:DATA_HOLDER'
      summary: List data holders
      tags:
        - data-holder
      responses:
        '200':
          description: >-
            Get a list of data holders by Provider, which can be filtered by
            country.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Providers'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/data-holder/{dataholderId}':
    parameters:
      - name: dataholderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: >-
          The id associated with the data holder the user wishes to authorise
          access to.
    get:
      description: >-
        Retrieves configuration and availability information for a specific data holder, including its provider, connection availability and supported permissions.
      operationId: getDataholder
      security:
        - apiKey: []
          userToken:
            - 'READ:DATA_HOLDER'
      summary: Get data holder
      tags:
        - data-holder
      responses:
        '200':
          description: Get a data holder
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataholder'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  '/data-holder/{dataholderId}/status':
    parameters:
      - name: dataholderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: >-
          The id associated with the data holder the user wishes to get the
          detailed state of.
    get:
      description: >-
        Retrieves detailed provider status information for the specified data holder.
      operationId: readDataholderState
      security:
        - apiKey: []
          userToken:
            - 'READ:PROVIDER'
      summary: Get data holder status
      tags:
        - data-holder
      responses:
        '200':
          description: Detailed dataholder information
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /user:
    post:
      description: |-
        Finds an application user by email address. If the user does not already exist, a new user is created and returned.
      operationId: findUserByEmail
      security:
       - apiKey: []
         clientToken: ["CREATE:USER"]
      summary: Find or create user
      tags:
      - app-user
      requestBody:
        $ref: '#/components/requestBodies/EmailRequest'
      responses:
        '200':
          description: |-
            Found
            The users of an app if an app is found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /user/{userId}:
    parameters:
    - name: userId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Id of the user
    get:
      description: |-
        Retrieves identity and profile information for the specified application user.
      operationId: readAppUserDetail
      security:
       - apiKey: []
         userToken: ["READ:APP_USER_DETAIL"]
      summary: Get user details
      tags:
      - app-user
      responses:
        '200':
          description: |-
            Found
            The user detail if found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetail'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /user/{userId}/details:
    parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Id of the user
    get:
      description: |-
        Retrieves user details available from all providers associated with the specified user.
      operationId: readAppUserDetails
      security:
        - apiKey: [ ]
          userToken: [ "READ:APP_USER_DETAIL" ]
      summary: Get provider user details
      tags:
        - app-user
      responses:
        '200':
          description: |-
            Found
            The user details if found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDetails'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
  /users:
    get:
      description: |-
        Retrieves the users registered within the application.
      operationId: readAppUsers
      security:
       - apiKey: []
         clientToken: ["READ:APP_USERS"]
      summary: List users
      tags:
      # documentation
      - app-user
      responses:
        '200':
          description: |-
            Found
            The users of an app if an app is found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Users'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
components:
  schemas:
    MagicLink:
      type: object
      properties:
        link:
          type: string
    AccessToken:
      type: object
      required:
        - access_token
        - token_type
        - expires_in
      properties:
        access_token:
          type: string
        token_type:
          type: string
        expires_in:
          type: integer
        refresh_token:
          type: string
        subscriber:
          type: string
          format: UUID
        profiles:
          type: array
          items:
            type: string
            format: UUID
        id_token:
          type: string
          description: >-
            This is defined as part of OIDC and used by 

            * ACCC [CDS OIDC
            Identifiers](https://consumerdatastandardsaustralia.github.io/standards/#tokens)
        number:
          type: string
        scope:
          type: string
          description: >-
            This is defined in the CDR register documentation as specifying the
            scopes available to the client.

            [CDR
            Register](https://cdr-register.github.io/register/#register-endpoints)
        cdr_arrangement_id:
          type: string
          description: >-
            The CDR Arrangement ID is a string representing a unique sharing
            arrangement between a data recipient and data holder for a given
            consumer

            [ACCC
            CDS](https://consumerdatastandardsaustralia.github.io/standards/#cdr-arrangement-id)
    BadRequest:
      type: object
      description: >-
        Bad Request

        The minimum header and parameter requirement for this request has not
        been met.
      example:
        code: 400
        id: 7d5ec75b-0142-437c-840f-ab5946481eaa
        message: The profile ID is required.
        type: BadRequest
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 400
        type:
          type: string
          default: BadRequest
    Created:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 201
        type:
          type: string
          default: Created
    Accepted:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 202
        type:
          type: string
          default: Accepted
    Error:
      type: object
      description: |-
        Service Unavailable
        An unexpected error has occurred. The service is currently unavailable.
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 500
        type:
          type: string
          default: Error
    Forbidden:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 403
        type:
          type: string
          default: Forbidden
    MethodNotAllowed:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 405
        type:
          type: string
          default: MethodNotAllowed
    NotFound:
      type: object
      example:
        type: NotFound
        id: 7d5ec75b-0142-437c-840f-ab5946481eaa
        message: No profile found for ID
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 404
        type:
          type: string
          default: NotFound
    OK:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 200
        type:
          type: string
          default: OK
    Unauthorised:
      type: object
      description: |-
        Unauthorised
        The minimum authorisation for the request has been met.
      example:
        code: 401
        message: This action requires permission.
        type: Unauthorised
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 401
        type:
          type: string
          default: Unauthorised
    UnprocessableEntity:
      type: object
      properties:
        message:
          type: string
        id:
          type: string
          format: uuid
        code:
          type: integer
          default: 422
        type:
          type: string
          default: UnprocessableEntity
    AccountStatus:
      type: string
      enum:
        - OPEN
        - CLOSED
        - ALL
    AccountType:
      type: string
      enum:
        - PERSONAL
        - BUSINESS
        - UNSPECIFIED
    AccountSubtype:
      type: string
      enum:
        - CHARGECARD
        - CREDITCARD
        - CURRENTACCOUNT
        - EMONEY
        - INVESTMENT
        - LOAN
        - OTHER
        - PENSION
        - MORTGAGE
        - PREPAIDCARD
        - SAVINGS
        - UNSPECIFIED
    BudgetCategory:
      type: string
      description: the transaction budget category
      enum:
        - INCOME
        - TRANSPORTATION
        - PERSONAL_DEVELOPMENT
        - MEDICAL_OR_HEALTHCARE
        - ENTERTAINMENT
        - HOUSING
        - FOOD
        - CHILDREN
        - INSURANCE
        - GIFTS
        - BILLS
        - PERSONAL_CARE
        - PETS
        - GOALS
        - DEBT
        - OTHER
    NumberScheme:
      type: string
      enum:
        - SORTCODE
        - IBAN
        - PAN
        - BIC
        - BBAN_SE
        - BBAN_DK
        - BBAN_NO
        - BECS
        - BSB_NO
        - MASKED
        - UNKNOWN
        - ABN
        - EMAIL
        - TELEPHONE
        - BPAY
        - ORG_ID
    ThirdPartyDirection:
      type: string
      enum:
        - PAYEE
        - PAYER
        - BOTH
        - UNKNOWN
    TransactionType:
      type: string
      enum:
        - CREDIT
        - DEBIT
        - UNKNOWN
    TransactionSubtype:
      type: string
      enum:
        - DIRECTDEBIT
        - FEE
        - INTEREST
        - TRANSFER
        - OTHER
        - PAYMENT
    TransactionStatus:
      type: string
      enum:
        - PENDING
        - POSTED
    Frequency:
      type: string
      enum:
        - YEAR
        - BIYEAR
        - QUARTER
        - MONTH
        - FORTNIGHT
        - WEEK
        - WEEKEND
        - BUSINESS
        - DAY
    DirectDebitIdentifierType:
      type: string
      enum:
        - ABN
        - ACN
        - ARBN
        - NZBN
    PayeeType:
      type: string
      enum:
        - BILLER
        - DIGITAL_WALLET
        - DOMESTIC
        - INTERNATIONAL
    PayeeSubtype:
      type: string
      enum:
        - ACCOUNT
        - CARD
        - PAYID
        - BILLER
    ProductCategory:
      type: string
      enum:
        - BUSINESS_LOANS
        - CRED_AND_CHRG_CARDS
        - LEASES
        - MARGIN_LOANS
        - OVERDRAFTS
        - PERS_LOANS
        - REGULATED_TRUST_ACCOUNTS
        - RESIDENTIAL_MORTGAGES
        - TERM_DEPOSITS
        - TRADE_FINANCE
        - TRANS_AND_SAVINGS_ACCOUNTS
        - TRAVEL_CARDS
    AccountNumber:
      type: object
      required:
        - scheme
        - number
      properties:
        scheme:
          $ref: '#/components/schemas/NumberScheme'
        number:
          type: string
    AccountNumbers:
      type: array
      items:
        $ref: '#/components/schemas/AccountNumber'
    Accounts:
      type: array
      items:
        $ref: '#/components/schemas/Account'
    Account:
      type: object
      required:
        - dataholder
        - currency
        - type
      properties:
        id:
          type: string
          format: uuid
          description: internal ID of account
        dataholder:
          type: string
          format: uuid
          description: internal ID of the data holder associated with this account
        user:
          type: string
          format: uuid
          description: ID of the user associated with this account
        app:
          type: string
          description: The app associated with this account
        connection:
          type: string
          format: uuid
          description: internal ID of the connection associated with this account
        currency:
          $ref: '#/components/schemas/Currency'
        externalId:
          type: string
          description: external ID used by the account providers
        status:
          $ref: '#/components/schemas/AccountStatus'
        type:
          $ref: '#/components/schemas/AccountType'
        subtype:
          $ref: '#/components/schemas/AccountSubtype'
        name:
          type: string
        nickname:
          type: string
        accountNumber:
          type: array
          items:
            $ref: '#/components/schemas/AccountNumber'
        productName:
          type: string
        creationDate:
          $ref : '#/components/schemas/OffsetDateTime'
        lendingRate :
          description : 'The current rate to calculate interest payable being applied to lending balances as it stands at the time of the API call'
          type : number
        lendingRates:
          type: array
          items:
            $ref: '#/components/schemas/LendingRate'
        loan :
          $ref : '#/components/schemas/Loan'
      example: 
        app: app
        loan: 
          originalLoanAmount : 6.027456183070403
          originalStartDate: 2000-01-23T04:56:07.000+00:00
          repaymentType: PRINCIPAL_AND_INTEREST
          repaymentFrequency: repaymentFrequency
          loanEndDate: 2000-01-23T04:56:07.000+00:00
        externalId: externalId
        type: PERSONAL
        accountNumber:
          - number: number
            scheme: SORTCODE
          - number: number
            scheme: SORTCODE
        creationDate: 2000-01-23T04:56:07.000+00:00
        productName: productName
        lendingRate : 0.8008281904610115
        lendingRates:
          - rate: 0.8008
            lendingRateType: VARIABLE
            additionalValue: "Debit excess interest rate"
            tiers:
              - name: DEBIT
                unitOfMeasure: DOLLAR
                minimumValue: 0.0
                maximumValue: 150000
        subtype: CHARGECARD
        name: name
        nickname: nickname
        connection: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        currency: USD, EUR, AUD, NZD
        id: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        user: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        dataholder: 046b6c7f-0b8a-43b9-b35d-6489e6daee91
        status: OPEN
    Amount:
      type: object
      required:
        - amount
        - currency
      properties:
        amount:
          type: number
          example: 123.45
        currency:
          $ref: '#/components/schemas/Currency'
    Balances:
      type: array
      items:
        $ref: '#/components/schemas/Balance'
    Balance:
      type: object
      required:
        - amount
        - date
      properties:
        id:
          type: string
          format: uuid
          description: internal ID of the account balance
        account:
          type: string
          format: uuid
          description: internal ID of the account the balance is associated with
        date:
          type: string
          format: date-time
          example: '2018-09-15T15:53:00Z'
          description: ISO 8601
        amount:
          $ref: '#/components/schemas/Amount'
        creditAvailable:
          type: number
          example: 123.45
    Currency:
      type: string
      description: ISO 4217 currency code
      example: 'USD, EUR, AUD, NZD'
    DirectDebitIdentifier:
      type: object
      required:
        - identifierType
        - identifier
      properties:
        identifierType:
          $ref: '#/components/schemas/DirectDebitIdentifierType'
        identifier:
          type: string
    DirectDebit:
      type: object
      properties:
        id:
          type: string
          format: uuid
        description:
          type: string
        facilitator:
          type: string
        identifiers:
          type: array
          items:
            $ref: '#/components/schemas/DirectDebitIdentifier'
    DirectDebits:
      type: array
      items:
        $ref: '#/components/schemas/DirectDebit'
    LendingRate:
      properties:
        id:
          type: string
          format: uuid
          description: internal ID of the lending rate
        lendingRateType:
          $ref: '#/components/schemas/LendingRateType'
        rate:
          description: The rate to be applied
          type: string
        tiers:
          description: Rate tiers applicable for this rate
          items:
            $ref: '#/components/schemas/RateTier'
          type: array
        additionalValue:
          type: string
      required:
        - lendingRateType
        - rate
      type: object
    LendingRateType:
      description: The type of rate (fixed, variable, etc). See the next section
        for an overview of valid values and their meaning
      enum:
        - BALANCE_TRANSFER
        - BUNDLE_DISCOUNT_FIXED
        - BUNDLE_DISCOUNT_VARIABLE
        - CASH_ADVANCE
        - DISCOUNT
        - FIXED
        - FLOATING
        - INTRODUCTORY
        - MARKET_LINKED
        - PENALTY
        - PURCHASE
        - VARIABLE
      type: string
    Loan:
      type: object
      properties:
        originalStartDate:
          format: date-time
          description: Optional original start date for the loan
          type: string
          allOf :
            - $ref: '#/components/schemas/OffsetDateTime'
        originalLoanAmount:
          description: Optional original loan value
          type: number
        loanEndDate:
          format: date-time
          description: Date that the loan is due to be repaid in full
          type: string
          allOf :
            - $ref: '#/components/schemas/OffsetDateTime'
        repaymentType:
          $ref: '#/components/schemas/LoanRepaymentType'
        repaymentFrequency:
          description: The expected or required repayment frequency. Formatted according to [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (excludes recurrence syntax)
          type: string
      example:
        originalLoanAmount : 6.027456183070403,
        originalStartDate: 2000-01-23T04:56:07.000+00:00
        repaymentType: PRINCIPAL_AND_INTEREST
        repaymentFrequency: repaymentFrequency
        loanEndDate: 2000-01-23T04:56:07.000+00:00
    LoanRepaymentType:
      type: string
      enum:
        - INTEREST_ONLY 
        - PRINCIPAL_AND_INTEREST
      description: Options in place for repayments. If absent defaults to PRINCIPAL_AND_INTEREST
      default: PRINCIPAL_AND_INTEREST
    OffsetDateTime:
      format: date-time
      type: string
      example: '2022-03-10T12:15:50-04:00'
    PayeeDetails:
      type: object
      properties:
        name:
          type: string
        accountNumber:
          $ref: '#/components/schemas/AccountNumber'
    Payee:
      type: object
      required:
        - id
        - externalId
        - nickname
        - type
      properties:
        id:
          type: string
          format: uuid
        externalId:
          type: string
        nickname:
          type: string
        description:
          type: string
        type:
          $ref: '#/components/schemas/PayeeType'
    Payees:
      type: array
      items:
        $ref: '#/components/schemas/Payee'
    Product:
      type: object
      properties:
        productId:
          type: string
        effectiveFrom:
          type: string
        effectiveTo:
          type: string
        lastUpdated:
          type: string
        productCategory:
          $ref: '#/components/schemas/ProductCategory'
        name:
          type: string
        description:
          type: string
        brand:
          type: string
        brandName:
          type: string
        applicationUri:
          type: string
        overviewUri:
          type: string
        termsUri:
          type: string
        eligibilityUri:
          type: string
        feesAndPricingUri:
          type: string
    RateTier:
      description: Defines the criteria and conditions for which a rate applies
      properties:
        id:
          type: string
          format: uuid
          description: internal ID of the tier
        name:
          description: A display name for the tier
          type: string
        unitOfMeasure:
          $ref: '#/components/schemas/TierUnitOfMeasureType'
        minimumValue:
          description: The number of unitOfMeasure units that form the lower bound
            of the tier. The tier should be inclusive of this value
          type: number
          x-cds-type: Number
        maximumValue:
          description: 'The number of unitOfMeasure units that form the upper bound
                of the tier or band. For a tier with a discrete value (as opposed to a
                range of values e.g. 1 month) this must be the same as minimumValue. Where
                this is the same as the minimumValue value of the next-higher tier the
                referenced tier should be exclusive of this value. For example a term
                deposit of 2 months falls into the upper tier of the following tiers:
                (1 – 2 months, 2 – 3 months). If absent the tier''s range has no upper
                bound.'
          type: number
          x-cds-type: Number
      required:
        - minimumValue
        - name
        - unitOfMeasure
      type: object
    TierUnitOfMeasureType:
      description: The unit of measure that applies to the minimumValue and maximumValue
        values e.g. a **DOLLAR** amount. **PERCENT** (in the case of loan-to-value
        ratio or LVR). Tier term period representing a discrete number of **MONTH**'s
        or **DAY**'s (in the case of term deposit tiers)
      enum:
        - DAY
        - DOLLAR
        - MONTH
        - PERCENT
      type: string
    ScheduledPayment:
      type: object
      properties:
        id:
          type: string
          format: uuid
        amount:
          $ref: '#/components/schemas/Amount'
        nickname:
          type: string
        payeeReference:
          type: string
        payerReference:
          type: string
        status":
          type: string
        type:
          $ref: '#/components/schemas/PayeeType'
        subType:
          $ref: '#/components/schemas/PayeeSubtype'
        payeeDetails:
          $ref: '#/components/schemas/PayeeDetails'
    ScheduledPayments:
      type: array
      items:
        $ref: '#/components/schemas/ScheduledPayment'
    ThirdParty:
      type: object
      required:
        - accountNumber
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        accountNumber:
          $ref: '#/components/schemas/AccountNumber'
        address:
          type: string
        reference:
          type: string
        direction:
          $ref: '#/components/schemas/ThirdPartyDirection'
    Transactions:
      type: array
      items:
        $ref: '#/components/schemas/Transaction'
    Transaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: internal ID of the transaction
        account:
          type: string
          format: uuid
          description: internal ID of the account
        reference:
          type: string
        type:
          $ref: '#/components/schemas/TransactionType'
        subtype:
          $ref: '#/components/schemas/TransactionSubtype'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        amount:
          $ref: '#/components/schemas/Amount'
        fee:
          $ref: '#/components/schemas/Amount'
        balance:
          $ref: '#/components/schemas/Amount'
        original:
          $ref: '#/components/schemas/Amount'
        exchangeRate:
          type: number
          example: 123.45
          description: original amount * exchange rate = amount
        datetime:
          type: string
          format: date-time
          example: '2018-09-15T15:53:00Z'
          description: ISO 8601
        externalId:
          type: string
        code:
          type: string
          description: the banking transaction code
        thirdParty:
          $ref: '#/components/schemas/ThirdParty'
        description:
          type: string
          description: the description of the transaction
        category:
          type: string
          description: the transaction business category
        subcategory:
          type: string
          description: the transaction business sub category
        budgetCategory:
          $ref: '#/components/schemas/BudgetCategory'
        budgetSubcategory:
          type: string
          description: the transaction budget sub category
        frequency:
          $ref: '#/components/schemas/Frequency'
    Partner:
      type: object
      required:
        - name
      properties:
        id:
          type: string
          description: the partner identifier
          format: uuid
        name:
          type: string
          description: the name of the partner
        externalId:
          type: string
          description: the external id of the partner
        url:
          type: string
          description: the URL of the business
        country:
          type: string
          description: the country of origin for the business
        region:
          type: string
          description: the region of the country the business is set up in
        industry:
          type: string
          description: what industry this business is registered for
        registeredNumber:
          type: string
          description: the business number of the partner
        taxNumber:
          type: string
          description: the tax number of the partner
    classifier:
      type: string
      enum:
        - merchant
        - category
        - movement
        - frequency
    classifierBudgetCategory:
      type: string
      enum:
        - INCOME
        - TRANSPORTATION
        - PERSONAL_DEVELOPMENT
        - MEDICAL_OR_HEALTHCARE
        - ENTERTAINMENT
        - HOUSING
        - FOOD
        - CHILDREN
        - INSURANCE
        - GIFTS
        - BILLS
        - PERSONAL_CARE
        - PETS
        - GOALS
        - DEBT
        - OTHER
    Period:
      type: string
      enum:
        - YEAR
        - BIYEAR
        - QUARTER
        - MONTH
        - FORTNIGHT
        - WEEK
        - WEEKEND
        - BUSINESS
        - DAY
    classifierAccountNumber:
      type: object
      required:
        - scheme
        - number
      properties:
        scheme:
          type: string
          enum:
            - SORTCODE
            - IBAN
            - PAN
            - BIC
            - BBAN_SE
            - BBAN_DK
            - BBAN_NO
            - BECS
            - BSB_NO
        number:
          type: string
    classifierThirdParty:
      type: object
      required:
        - accountNumber
      properties:
        name:
          type: string
        accountNumber:
          $ref: '#/components/schemas/classifierAccountNumber'
        address:
          type: string
        reference:
          type: string
    classifierTransactions:
      type: array
      items:
        $ref: '#/components/schemas/classifierTransaction'
    classifierTransaction:
      type: object
      properties:
        id:
          type: string
          description: >-
            ID of the transaction (Will be replayed in the classified
            transactions)
        account:
          type: string
          format: uuid
          description: The wych account that this transaction belongs to (Optional)
        type:
          type: string
          enum:
            - CREDIT
            - DEBIT
        status:
          type: string
          enum:
            - PENDING
            - POSTED
        amount:
          $ref: '#/components/schemas/Amount'
        fee:
          $ref: '#/components/schemas/Amount'
        balance:
          $ref: '#/components/schemas/Amount'
        original:
          $ref: '#/components/schemas/Amount'
        exchangeRate:
          type: number
          example: 123.45
          description: original amount * exchange rate = amount
        datetime:
          type: string
          format: date-time
          example: '2018-09-15T15:53:00Z'
          description: ISO 8601
        externalId:
          type: string
        code:
          type: string
          description: the banking transaction code
        thirdParty:
          $ref: '#/components/schemas/classifierThirdParty'
        description:
          type: string
          description: the description of the transaction
        category:
          type: string
          description: the transaction category
        subcategory:
          type: string
          description: the transaction sub category
    ClassifiedTransactions:
      type: array
      items:
        $ref: '#/components/schemas/ClassifiedTransaction'
    ClassifiedTransaction:
      type: object
      properties:
        id:
          type: string
          description: ID of the transaction
        account:
          type: string
          format: uuid
          description: The wych account
        business:
          type: string
          description: the Business associated with the transaction
        merchant:
          type: object
          properties:
            name:
              type: string
            location:
              type: string
            categoryCode:
              type: integer
        category:
          type: object
          properties:
            name:
              type: string
              description: the transaction category
            subcategory:
              type: string
              description: the transaction sub category
        budget:
          type: object
          properties:
            category:
              $ref: '#/components/schemas/classifierBudgetCategory'
            subcategory:
              type: string
        movement:
          type: object
          properties:
            how:
              type: string
        frequency:
          type: object
          properties:
            period:
              $ref: '#/components/schemas/Period'
    AccessLevelEnum:
      type: string
      enum:
        - ADMIN
    ConnectionStateEnum:
      type: string
      enum:
        - ACTIVE
        - EXPIRED
        - DISCONNECTED
        - INITIATED
    ExtractionStateEnum:
      type: string
      enum:
        - SUCCESS
        - FAILURE
    ExtractionTypeEnum:
      type: string
      enum:
        - BANK_ACCOUNT
        - BANK_BALANCE
        - BANK_TRANSACTION
        - USER_INFO
    AppConfiguration:
      type: object
      properties:
        redirectUri:
          type: string
    AccessLevel:
      type: object
      properties:
        user:
          type: string
          format: uuid
        accessLevel:
          $ref: '#/components/schemas/AccessLevelEnum'
    ClientRedirect:
      type: object
      properties:
        redirectUri:
          type: string
    Connection:
      type: object
      description: >-
        The system entity representing the link between a user and a
        dataholder, 

        this entity will optionally contain what metrics this connection was
        created for.
      properties:
        id:
          type: string
          format: UUID
          description: The id for this connection
        app:
          type: string
          description: The app this connection belongs to
        dataholder:
          type: string
          format: UUID
          description: The dataholder id which this connection pulls data from
        user:
          type: string
          format: UUID
          description: The id of the user associated with this connection
        scopes:
          type: array
          nullable: true
          description: >-
            The scopes that have been applied to this connection from the
            dataholder,

            will be null if the connection is not in an active, expired or
            disconnected state
          items:
            type: string
        metrics:
          type: array
          nullable: true
          description: >-
            The metrics associated with this connection, this will be null if it
            is all metrics
          items:
            type: string
        status:
          $ref: '#/components/schemas/ConnectionStateEnum'
        connectionState:
          $ref: '#/components/schemas/ConnectionState'
    Connections:
      type: array
      items:
        $ref: '#/components/schemas/Connection'
    ConnectionDataRefresh:
      type: object
      properties:
        refreshIntervalDays:
          description: 'The amount of days to refresh the data for, from today and backwards'
          type: integer
          minimum: 1
          maximum: 730
          default: 1
        scopes:
          description: 'This is the list of scopes to refresh data for'
          type: array
          items:
            $ref: '#/components/schemas/ExtractionTypeEnum'
          nullable: true
          default: [BANK_TRANSACTION]
    ConnectionState:
      type: object
      description: >-
        The connection state represents a the current status of the connection
        including timestamps of things that have occurred
      properties:
        status:
          $ref: '#/components/schemas/ConnectionStateEnum'
        connectedAt:
          type: string
          format: date-time
        disconnectedAt:
          type: string
          format: date-time
        BANK_ACCOUNT:
          $ref: '#/components/schemas/ExtractionRecording'
        BANK_BALANCE:
          $ref: '#/components/schemas/ExtractionRecording'
        BANK_TRANSACTION:
          $ref: '#/components/schemas/ExtractionRecording'
        USER_INFO:
          $ref: '#/components/schemas/ExtractionRecording'
    ExtractionRecording:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/ExtractionStateEnum'
        referenceId:
          type: string
        lastSuccess:
          type: string
          format: date-time
        lastUpdated:
          type: string
          format: date-time
    ExtractionStarted:
      type: object
      description: >-
        This object is used to record a new extraction run for a particular type
        of information.

        It pairs with the ExtractionFinished object to mark an extraction as
        finished
      properties:
        extractionId:
          type: string
          format: uuid
          description: The unique identifier for this extraction run
        referenceId:
          type: string
          description: 'A possible reference id, often times an account external id'
        startedAt:
          type: string
          format: date-time
          description: The time when the extraction was started
        type:
          $ref: '#/components/schemas/ExtractionTypeEnum'
    ExtractionFinished:
      type: object
      description: >-
        This object is used to record an extraction run as completed for a
        particular type of information.

        It pairs with the ExtractionStarted object to mark an extraction as
        finished

        This api will throw an error if extraction started request was not
        recorded
      properties:
        finishedAt:
          type: string
          format: date-time
          description: The time when the extraction was finished
        referenceId:
          type: string
          description: 'A possible reference id, often times an account external id'
        type:
          $ref: '#/components/schemas/ExtractionTypeEnum'
        status:
          $ref: '#/components/schemas/ExtractionStateEnum'
        message:
          type: string
          description: Any comments as a result of the extraction
    ExtractionState:
      type: object
      description: >-
        The extraction state capture the complete entity created by the
        ExtractionStarted and ExtractionFinished api calls.

        The extraction need not be finished to be returned in the case of
        extractions that are still in progress
      required:
        - status
        - type
      properties:
        status:
          $ref: '#/components/schemas/ExtractionStateEnum'
        type:
          $ref: '#/components/schemas/ExtractionTypeEnum'
        referenceId:
          type: string
          description: 'A possible reference id, often times an account external id'
        startedAt:
          type: string
          format: date-time
          description: The time when the extraction was started
        finishedAt:
          type: string
          format: date-time
          description: The time when the extraction was finished
        message:
          type: string
          description: Any comments as a result of the extraction
    Dataholder:
      type: object
      required:
        - name
      properties:
        id:
          type: string
          format: uuid
        app:
          type: string
        name:
          type: string
        friendlyName:
          type: string
        country:
          type: string
          format: ISO 3166
        connectable:
          type: boolean
        enabled:
          type: boolean
        logoUri:
          type: string
        provider:
          type: string
        externalId:
          type: string
        extractorId:
          type: string
          format: uuid
        permissions:
          $ref: '#/components/schemas/DataholderPermissions'
    DataholderPermissions:
      type: object
      additionalProperties:
        type: string
    Providers:
      type: array
      items:
        $ref: '#/components/schemas/data-holderProvider'
    data-holderProvider:
      type: object
      required:
        - basepath
        - externalId
        - app
      properties:
        id:
          type: string
          format: UUID
        externalId:
          type: string
        app:
          type: string
        name:
          type: string
        recipientId:
          type: string
        recipientName:
          type: string
        providerKey:
          type: string
        basepath:
          type: string
          format: URL
          nullable: true
        dataHolders:
          type: array
          items:
            $ref: '#/components/schemas/Dataholder'
    data-holderProviderConfiguration:
      type: object
      properties:
        app:
          type: string
      additionalProperties:
        type: string
    Users:
      type: array
      items:
        $ref: '#/components/schemas/User'
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
    UserDetail:
      type: object
      properties:
        id:
          description: internal ID of user
          type: string
          format: uuid
        sub:
          type: string
          format: UUID
        userInfo:
          $ref: '#/components/schemas/UserInfo'
    UserDetails:
      type: object
      properties:
        id:
          description: internal ID of user
          type: string
          format: uuid
        sub:
          type: string
          format: UUID
        userInfo:
          type: array
          items:
            $ref: '#/components/schemas/UserInfo'
    UserInfo:
      type: object
      properties:
        sub:
          type: string
          format: UUID
        name:
          type: string
        family_name:
          type: string
        given_name:
          type: string
        middle_name:
          type: string
        nickname:
          type: string
        preferred_username:
          type: string
        profile:
          type: string
        picture:
          type: string
        website:
          type: string
        email:
          type: string
        email_verified:
          type: boolean
        gender:
          type: string
        birthdate:
          type: string
          format: date
        zone_info:
          type: string
        locale:
          type: string
        phone_number:
          type: string
        phone_number_verified:
          type: boolean
        address:
          $ref: '#/components/schemas/Address'
    Address:
      type: object
      properties:
        formatted:
          type: string
        street_address:
          type: string
        locality:
          type: string
        region:
          type: string
        postal_code:
          type: string
        country:
          type: string
  responses:
    '200':
      description: OK
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OK'
    '201':
      description: |-
        Created
        The response object contains the ID of the created object.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Created'
    '202':
      description: |-
        Accepted
        The request has been accepted for processing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Accepted'
    '204':
      description: |-
        No content
        The request has been accepted for processing.
    '400':
      description: >-
        Bad Request

        The minimum header and parameter requirement for this request has not
        been met.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
    '401':
      description: |-
        Unauthorised
        The minimum authorisation for the request has been met. 
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorised'
    '403':
      description:  |-
        Forbidden
        The minimum authorisation for the request has not been met. 
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Forbidden'
    '404':
      description: |-
        Not Found
        The requested entity could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFound'
    '422':
      description: |-
        Unprocessable Entity
        The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnprocessableEntity'
    '500':
      description: |-
        Service Unavailable
        The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    HistoricInsights:
      description: The list of historic insight executions
      content:
        application/json:
          schema:
            type: object
            additionalProperties:
              type: string
              format: uuid
  parameters:
    profileId:
      description: Id of the profile
      in: header
      name: profileId
      required: true
      schema:
        type: string
        format: uuid
    version:
      description: >-
        The version number of the API you wish to connect to. See the API
        overview for more information.
      in: header
      name: x-v
      required: true
      schema:
        type: integer
        minimum: 1
  examples:
    account-transactions-request:
      summary: Account transactions
      description: Get the transactions for each account
      value:
        metrics:
          - 'account:transaction:amount'
        dimensions:
          - 'account:name'
    account-transactions-response:
      summary: Account transactions
      value:
        - 'account:transaction:amount': 100
          'account:name': Default
        - 'account:transaction:amount': 1045.2
          'account:name': Sourced
    account-balance-request:
      summary: Account Balances
      description: Get the balances for each account
      value:
        metrics:
          - 'account:balance'
        dimensions:
          - 'account:name'
          - 'account:category'
    account-balance-response:
      summary: Account Balances
      value:
        - 'account:balance': 100
          'account:name': Checking
          'account:category': Cash
        - 'account:balance': 2340.56
          'account:name': House Deposit
          'account:category': Savings
        - 'account:balance': 1000
          'account:name': Car Deposit
          'account:category': Savings
    account-category-balance-request:
      summary: Account Balances by Category
      description: Get the aggregated balances for each category
      value:
        metrics:
          - 'account:balance'
        dimensions:
          - 'account:category'
    account-category-balance-response:
      summary: Account Balances by Category
      value:
        - 'account:balance': 100
          'account:category': Cash
        - 'account:balance': 3340.56
          'account:category': Savings
  requestBodies:
    Account:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Account'
    Accounts:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Accounts'
    AccountNumber:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountNumber'
    Balance:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Balance'
    Transaction:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Transaction'
    Transactions:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Transactions'
    PartnerRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Partner'
    classifierTransactions:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/classifierTransactions'
    AccessLevel:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccessLevel'
    AppConfiguration:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AppConfiguration'
    Connection:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Connection'
    ConnectionDataRefresh:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ConnectionDataRefresh'
    ExtractionStarted:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExtractionStarted'
    ExtractionFinished:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ExtractionFinished'
    Provider:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/data-holderProvider'
    ProviderConfigurationRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/data-holderProviderConfiguration'
    Dataholder:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              enabled:
                type: boolean
    EmailRequest:
      required: true
      content:
        application/json:
          schema:
            type: object
            properties:
              email:
                type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Wych gateway API key, this key can be found in the Wych customer portal.'
    clientToken:
      type: oauth2
      description: 'You retrieve this by using client credentials grant.'
      flows:
        clientCredentials:
          tokenUrl: /realms/{app}/protocol/openid-connect/token
          scopes: {'READ:APP_USERS': Read all users associated with an app, 'EXECUTE:TOKEN_EXCHANGE': Retrieve the user token}
    userToken:
      description: 'You retrieve your user token as part of a token exchange, see [Retrieve the user token](#tag/auth-token/operation/retrieveAppUserToken) for more information.'
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - apiKey: []
    clientToken: []
  - apiKey: []
    userToken: []