openapi: 3.0.3
info:
  title: Mono Connect Financial Data API
  description: 'A grounded subset of the Mono open banking API for Africa. Mono lets businesses link customer bank accounts and read financial data, assess creditworthiness, collect direct bank payments (DirectPay), and verify identity (Lookup). Server-to-server requests authenticate with a secret key sent in the `mono-sec-key` header. Account linking is completed by the customer through the hosted Mono Connect widget; the widget returns a short-lived authorization code that is exchanged for a permanent account id used on all financial-data calls.


    Endpoint paths and methods here are grounded in the public Mono documentation at docs.mono.co (base host `https://api.withmono.com`, most endpoints under `/v2`; the account-number and Mashup Lookup endpoints are under `/v3`). Request and response bodies are modeled representatively - treat field-level schemas as illustrative and confirm exact payloads against the live reference before relying on them.'
  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:
    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
    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
    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.
    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
    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
    Balance:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        account_number:
          type: string
        balance:
          type: integer
        currency:
          type: string
  parameters:
    AccountId:
      name: id
      in: path
      required: true
      description: The permanent account id returned by the exchange-token endpoint.
      schema:
        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'
  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.