openapi: 3.2.0
info:
  title: Mono Connect Financial Data API
  description: A grounded subset of the Mono open banking API for Africa.
  version: '2.0'
  contact:
    name: Mono
    url: https://mono.co
  x-provenance: Endpoint paths/methods grounded in docs.mono.co (2026-07-12). Request/response schemas are modeled and should be reconciled against the live API reference.
servers:
- url: https://api.withmono.com
  description: Mono production API host
security:
- monoSecKey: []
tags:
- name: Financial Data
  description: Read financial data from a linked account.
paths:
  /v2/accounts:
    get:
      operationId: getAccounts
      tags:
      - Financial Data
      summary: Get accounts
      description: Retrieves the linked accounts associated with your application.
      responses:
        '200':
          description: A list of linked accounts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/{id}:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getAccountDetails
      tags:
      - Financial Data
      summary: Account details
      description: Retrieves the details and metadata of a single linked account.
      responses:
        '200':
          description: Account details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/accounts/{id}/transactions:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getTransactions
      tags:
      - Financial Data
      summary: Transactions
      description: Retrieves transactions on a linked account. Supports pagination and date filtering. When the `x-real-time` header is enabled, transactions are fetched in real time from the institution.
      parameters:
      - name: start
        in: query
        description: Start date filter (DD-MM-YYYY).
        schema:
          type: string
      - name: end
        in: query
        description: End date filter (DD-MM-YYYY).
        schema:
          type: string
      - name: narration
        in: query
        description: Filter transactions by narration text.
        schema:
          type: string
      - name: type
        in: query
        description: Filter by transaction type (debit or credit).
        schema:
          type: string
          enum:
          - debit
          - credit
      - name: paginate
        in: query
        description: Whether to paginate the response.
        schema:
          type: boolean
      responses:
        '200':
          description: A list of transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/{id}/identity:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getIdentity
      tags:
      - Financial Data
      summary: Identity
      description: Retrieves KYC identity information tied to a linked account.
      responses:
        '200':
          description: Identity information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Identity'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/{id}/balance:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getBalance
      tags:
      - Financial Data
      summary: Account balance
      description: Retrieves the real-time balance of a linked account.
      responses:
        '200':
          description: Account balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Balance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/{id}/income:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getIncome
      tags:
      - Financial Data
      summary: Income
      description: Retrieves income analysis for a linked account - estimated regular income, employer, and confidence signals derived from transaction history.
      responses:
        '200':
          description: Income analysis.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Income'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/{id}/statement:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    get:
      operationId: getStatement
      tags:
      - Financial Data
      summary: Bank statement
      description: Retrieves a bank statement for a linked account. Set `output=pdf` to request a PDF; the response then returns a job/path that is polled for the generated document.
      parameters:
      - name: period
        in: query
        description: Statement period, e.g. `last6months` or `last12months`.
        schema:
          type: string
      - name: output
        in: query
        description: Response format - `json` (default) or `pdf`.
        schema:
          type: string
          enum:
          - json
          - pdf
      responses:
        '200':
          description: Statement data (or a PDF generation reference).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Statement'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/accounts/{id}/unlink:
    parameters:
    - $ref: '#/components/parameters/AccountId'
    post:
      operationId: unlinkAccount
      tags:
      - Financial Data
      summary: Unlink account
      description: Unlinks a previously linked account, revoking further data access.
      responses:
        '200':
          description: The account was unlinked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Statement:
      type: object
      properties:
        meta:
          type: object
          properties:
            count:
              type: integer
        account:
          $ref: '#/components/schemas/Account'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        path:
          type: string
          description: When output=pdf, the path/URL to poll for the generated PDF.
    Error:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
    Income:
      type: object
      properties:
        type:
          type: string
        amount:
          type: number
        employer:
          type: string
        employment_status:
          type: string
        income_confidence:
          type: string
        last_income_date:
          type: string
    Balance:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        account_number:
          type: string
        balance:
          type: integer
        currency:
          type: string
    Transaction:
      type: object
      properties:
        id:
          type: string
        narration:
          type: string
        amount:
          type: integer
          description: Amount in the account's minor currency unit (kobo for NGN).
        type:
          type: string
          enum:
          - debit
          - credit
        balance:
          type: integer
        date:
          type: string
          format: date-time
        category:
          type: string
    Identity:
      type: object
      properties:
        full_name:
          type: string
        email:
          type: string
        phone:
          type: string
        gender:
          type: string
        dob:
          type: string
        bvn:
          type: string
        marital_status:
          type: string
        address_line1:
          type: string
    Account:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        currency:
          type: string
        type:
          type: string
        account_number:
          type: string
        balance:
          type: number
        bvn:
          type: string
        institution:
          type: object
          properties:
            name:
              type: string
            bank_code:
              type: string
            type:
              type: string
  responses:
    Unauthorized:
      description: The `mono-sec-key` is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    AccountId:
      name: id
      in: path
      required: true
      description: The permanent account id returned by the exchange-token endpoint.
      schema:
        type: string
  securitySchemes:
    monoSecKey:
      type: apiKey
      in: header
      name: mono-sec-key
      description: Secret key for the application, found in the Mono dashboard. Sent on every server-to-server request in the `mono-sec-key` header. Use test keys in the sandbox and live keys in production.