openapi: 3.0.3
info:
  title: Basiq API
  description: >-
    The Basiq API is an open banking and financial data platform providing unified
    access to Australian and New Zealand bank account data. It enables financial
    applications to retrieve account balances, transactions, income verification,
    and expense categorization via consumer-consented bank connections using CDR
    (Consumer Data Right) and third-party open banking standards.
  version: 3.0.0
  contact:
    name: Basiq Support
    url: https://basiq.io/contact
  termsOfService: https://basiq.io/legal/terms-of-use/
servers:
  - url: https://au-api.basiq.io
    description: Basiq API (Australia)
security:
  - BearerAuth: []
paths:
  /token:
    post:
      operationId: createToken
      summary: Create Token
      description: Exchange API key for a server token or user token for API access.
      tags:
        - Authentication
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum: [client_credentials]
                scope:
                  type: string
                  description: "SERVER_ACCESS or CLIENT_ACCESS"
              required:
                - grant_type
      responses:
        '200':
          description: Access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
  /users:
    post:
      operationId: createUser
      summary: Create User
      description: Create a new Basiq user representing an end consumer.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
  /users/{userId}:
    get:
      operationId: getUser
      summary: Get User
      description: Retrieve a user by ID.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: User record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteUser
      summary: Delete User
      description: Delete a user and all associated connections and data.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '204':
          description: User deleted
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{userId}/connections:
    get:
      operationId: listConnections
      summary: List Connections
      description: List all bank connections for a user.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: List of connections
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createConnection
      summary: Create Connection
      description: Create a new bank connection for a user.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectionRequest'
      responses:
        '201':
          description: Connection created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '400':
          $ref: '#/components/responses/BadRequest'
  /users/{userId}/connections/{connectionId}:
    get:
      operationId: getConnection
      summary: Get Connection
      description: Retrieve a specific bank connection.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ConnectionId'
      responses:
        '200':
          description: Connection record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Connection'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteConnection
      summary: Delete Connection
      description: Remove a bank connection and revoke consent.
      tags:
        - Connections
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/ConnectionId'
      responses:
        '204':
          description: Connection deleted
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{userId}/accounts:
    get:
      operationId: listAccounts
      summary: List Accounts
      description: List all bank accounts for a user across all connections.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: List of accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{userId}/accounts/{accountId}:
    get:
      operationId: getAccount
      summary: Get Account
      description: Retrieve a specific bank account with balance information.
      tags:
        - Accounts
      parameters:
        - $ref: '#/components/parameters/UserId'
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Account record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{userId}/transactions:
    get:
      operationId: listTransactions
      summary: List Transactions
      description: List all transactions for a user across all accounts with optional filtering.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/UserId'
        - name: filter
          in: query
          description: Filter transactions by date range, account, or category
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 500
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{userId}/transactions/{transactionId}:
    get:
      operationId: getTransaction
      summary: Get Transaction
      description: Retrieve a specific transaction by ID.
      tags:
        - Transactions
      parameters:
        - $ref: '#/components/parameters/UserId'
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Transaction record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{userId}/income:
    get:
      operationId: getIncomeVerification
      summary: Get Income Verification
      description: Get income verification data derived from transaction analysis.
      tags:
        - Affordability
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Income verification report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncomeVerification'
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{userId}/expenses:
    get:
      operationId: getExpenses
      summary: Get Expenses
      description: Get categorized expense data derived from transaction analysis.
      tags:
        - Affordability
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Expense report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExpenseReport'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    UserId:
      name: userId
      in: path
      required: true
      description: Basiq user ID
      schema:
        type: string
    ConnectionId:
      name: connectionId
      in: path
      required: true
      description: Basiq connection ID
      schema:
        type: string
    AccountId:
      name: accountId
      in: path
      required: true
      description: Basiq account ID
      schema:
        type: string
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT access token
        token_type:
          type: string
          description: Token type (Bearer)
        expires_in:
          type: integer
          description: Token expiry in seconds
    CreateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          description: User email address
        mobile:
          type: string
          description: User mobile number in E.164 format
        firstName:
          type: string
        lastName:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
          description: Basiq user ID
        email:
          type: string
        mobile:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        createdDate:
          type: string
          format: date-time
      required:
        - id
        - email
    CreateConnectionRequest:
      type: object
      properties:
        institutionId:
          type: string
          description: Basiq institution ID for the bank
        loginId:
          type: string
          description: User's bank login ID
        password:
          type: string
          description: User's bank password (encrypted in transit)
      required:
        - institutionId
    Connection:
      type: object
      properties:
        id:
          type: string
          description: Connection ID
        status:
          type: string
          enum: [active, pending, failed, disconnected]
        institution:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
        lastUpdated:
          type: string
          format: date-time
    ConnectionListResponse:
      type: object
      properties:
        type:
          type: string
          default: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Connection'
        size:
          type: integer
    Account:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: Account name
        accountNo:
          type: string
          description: Masked account number
        currency:
          type: string
          description: ISO 4217 currency code
        balance:
          type: number
          format: double
          description: Current balance
        availableFunds:
          type: number
          format: double
          description: Available funds
        accountType:
          type: string
          enum: [transaction, savings, credit-card, mortgage, loan, investment]
        status:
          type: string
          enum: [available, unavailable]
    AccountListResponse:
      type: object
      properties:
        type:
          type: string
          default: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Account'
        size:
          type: integer
    Transaction:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [posted, pending]
        description:
          type: string
          description: Raw transaction description from bank
        amount:
          type: number
          format: double
        balance:
          type: number
          format: double
        direction:
          type: string
          enum: [credit, debit]
        class:
          type: string
          description: Basiq transaction class (e.g., payment, transfer)
        subClass:
          type: object
          properties:
            title:
              type: string
            code:
              type: string
        transactionDate:
          type: string
          format: date
        postDate:
          type: string
          format: date
    TransactionListResponse:
      type: object
      properties:
        type:
          type: string
          default: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        size:
          type: integer
        totalCount:
          type: integer
    IncomeVerification:
      type: object
      properties:
        userId:
          type: string
        summary:
          type: object
          properties:
            regular:
              type: object
              properties:
                monthly:
                  type: number
                annual:
                  type: number
            irregular:
              type: object
              properties:
                monthly:
                  type: number
        incomeStreams:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              amount:
                type: number
              frequency:
                type: string
    ExpenseReport:
      type: object
      properties:
        userId:
          type: string
        summary:
          type: object
          properties:
            totalMonthly:
              type: number
        categories:
          type: array
          items:
            type: object
            properties:
              category:
                type: string
              amount:
                type: number
              percentage:
                type: number
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
        title:
          type: string
        code:
          type: string
        detail:
          type: string
        source:
          type: object