openapi: 3.0.3
info:
  title: Mono Connect Lookup 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: Lookup
  description: Identity and data verification for KYC/KYB.
paths:
  /v2/lookup/bvn/initiate:
    post:
      operationId: lookupBvnInitiate
      tags:
      - Lookup
      summary: Initiate BVN lookup
      description: Initiates a consent-based BVN verification. The customer consents to the lookup (for example via an OTP/iGree flow) before verified details are returned. Modeled path - confirm the exact BVN sub-path against the live reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BvnInitiateRequest'
      responses:
        '200':
          description: A BVN verification session was initiated.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  message:
                    type: string
                  data:
                    type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/lookup/account-number:
    post:
      operationId: lookupAccountNumber
      tags:
      - Lookup
      summary: Account-number lookup
      description: Verifies ownership of a bank account by account number and bank code, returning the resolved account name. Served under the `/v3/lookup` path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountNumberLookupRequest'
      responses:
        '200':
          description: Resolved account holder information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v3/lookup/mashup:
    post:
      operationId: lookupMashup
      tags:
      - Lookup
      summary: Mashup lookup
      description: Cross-checks a customer's submitted identity against multiple sources in a single call (the Mashup Lookup). Served under the `/v3/lookup` path.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Aggregated identity verification result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  data:
                    type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    BvnInitiateRequest:
      type: object
      required:
      - bvn
      - scope
      properties:
        bvn:
          type: string
          description: The Bank Verification Number to verify.
        scope:
          type: string
          description: The consent scope, e.g. `identity`.
    AccountNumberLookupRequest:
      type: object
      required:
      - nip_code
      - account_number
      properties:
        nip_code:
          type: string
          description: The bank/institution NIP code.
        account_number:
          type: string
    Error:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
  responses:
    Unauthorized:
      description: The `mono-sec-key` is missing or invalid.
      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.