> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kirafin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List virtual accounts

> Use `limit<=100` — `limit` above `100` returns a clean `400` validation error (same cap as `GET /v1/users`; applies to ALL list endpoints). There is no top-level `provider` or `currency` on a virtual account — the rail is exposed as `bank`, and a crypto VA's currency is under `destination.currency` (identical in list and get-by-id views).

**Status filter vs. response status:** the `status` query filter uses the **raw** lifecycle values (`pending`, `activating`, `active`, `failed`, `deactivated`), while the `status` on each returned account is the **KYB-mapped** value (`approved`, `rfi`, `declined`, `deactivated`). Filter on raw; read the mapped value off the response.

{/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */}

<Update label="2026-04-14">Changed in this version.</Update>

{/* version-stamp:end */}


## OpenAPI

````yaml /openapi/kira-api.2026-04-14.json get /v1/virtual-accounts
openapi: 3.1.0
info:
  title: Kira API
  version: '2026-04-14'
  description: >-
    REST API for users, KYC/KYB verification, virtual accounts, payouts,
    recipients, and webhooks. Every request requires an `x-api-key` header and a
    bearer access token (see Authentication). Pin your account to version
    `2026-04-14` before integrating.
  contact:
    name: Kira API Support
    email: support@kirafin.ai
servers:
  - url: https://api.balampay.com
    description: Production
  - url: https://api.balampay.com/sandbox
    description: Sandbox
security:
  - bearerAuth: []
    apiKeyAuth: []
tags:
  - name: Authentication
  - name: Versioning
  - name: Users
  - name: Virtual Accounts
  - name: Quotations
  - name: Payouts
  - name: Recipients
  - name: Reference
paths:
  /v1/virtual-accounts:
    get:
      tags:
        - Virtual Accounts
      summary: List virtual accounts
      description: >-
        Use `limit<=100` — `limit` above `100` returns a clean `400` validation
        error (same cap as `GET /v1/users`; applies to ALL list endpoints).
        There is no top-level `provider` or `currency` on a virtual account —
        the rail is exposed as `bank`, and a crypto VA's currency is under
        `destination.currency` (identical in list and get-by-id views).


        **Status filter vs. response status:** the `status` query filter uses
        the **raw** lifecycle values (`pending`, `activating`, `active`,
        `failed`, `deactivated`), while the `status` on each returned account is
        the **KYB-mapped** value (`approved`, `rfi`, `declined`, `deactivated`).
        Filter on raw; read the mapped value off the response.
      operationId: get_v1-virtual-accounts
      parameters:
        - in: header
          name: X-Api-Version
          required: false
          description: >-
            Optional. The date-versioned API version to apply for this request
            (e.g. `2026-04-14`). When sent it always wins, even over your pinned
            account default. When omitted, the API uses your account's pinned
            version if set, otherwise a baseline default.
          schema:
            type: string
            example: '2026-04-14'
        - in: query
          name: limit
          required: false
          description: Maximum number of virtual accounts to return (1-100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: offset
          required: false
          description: Number of virtual accounts to skip for pagination.
          schema:
            type: integer
            minimum: 0
            default: 0
        - in: query
          name: status
          required: false
          description: >-
            Filter by **raw** account status (not the KYB-mapped value shown on
            the response).
          schema:
            type: string
            enum:
              - pending
              - activating
              - active
              - failed
              - deactivated
        - in: query
          name: user_id
          required: false
          description: Filter by owning user UUID.
          schema:
            type: string
            format: uuid
        - in: query
          name: type
          required: false
          description: Filter by virtual account type.
          schema:
            type: string
            enum:
              - US_BANK
        - in: query
          name: mode
          required: false
          description: Filter by funding mode.
          schema:
            type: string
            enum:
              - fiat
              - crypto
        - in: query
          name: search
          required: false
          description: Free-text search (1-255 characters).
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - in: query
          name: metadata
          required: false
          description: >-
            Stripe-style metadata filter — `?metadata[key]=value` deep-object
            form. Each key must be 1-40 characters and must not contain `[` or
            `]`. Multiple keys are AND-ed.
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: Paginated list envelope (offset-based).
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/VirtualAccount'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Total virtual accounts matching the filters.
                      limit:
                        type: integer
                        description: The limit applied to this page.
                      offset:
                        type: integer
                        description: The offset applied to this page.
                      has_more:
                        type: boolean
                        description: Whether more virtual accounts exist beyond this page.
                required:
                  - data
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
          apiKeyAuth: []
components:
  schemas:
    VirtualAccount:
      type: object
      description: >-
        A virtual account as returned by the VA read endpoints (`GET
        /v1/virtual-accounts`, `GET /v1/virtual-accounts/{virtual_account_id}`).
        On the `2026-04-14` pin, `status` is the KYB-mapped value (see the enum)
        and bank details are projected as flat top-level fields. The list view
        returns a thinner projection: `markup` is present only when fetching a
        single VA by ID, and `provider`/`currency` come back `null` in the list.
        All fields beyond the `required` set may be absent or `null`.
      properties:
        id:
          type: string
          format: uuid
          description: Virtual account UUID.
        user_id:
          type: string
          format: uuid
          description: UUID of the user that owns this virtual account.
        status:
          type: string
          enum:
            - approved
            - rfi
            - declined
            - deactivated
          description: >-
            KYB-mapped account status (the response shape on the `2026-04-14`
            pin). Internally `active`/`activating` surface as `approved`,
            `pending` as `rfi`, and `failed` as `declined`; `deactivated` passes
            through. Note the `status` query filter on the list endpoint uses
            the **raw** values (`pending`, `activating`, `active`, `failed`,
            `deactivated`) instead.
        type:
          type: string
          enum:
            - US_BANK
          description: Virtual account type.
        bank:
          type:
            - string
            - 'null'
          description: Selected bank/provider rail (e.g. `slovak_savings_bank` in sandbox).
        mode:
          type: string
          enum:
            - fiat
            - crypto
          description: Funding mode. Fixed at creation.
        destination:
          type:
            - object
            - 'null'
          description: >-
            Crypto payout destination (`currency`, `network`, `address`). `null`
            for fiat-mode accounts.
          additionalProperties: true
        source_deposit_instructions:
          type:
            - object
            - 'null'
          description: >-
            Provider deposit instructions the flat bank fields are projected
            from.
          additionalProperties: true
        payment_methods:
          type:
            - object
            - 'null'
          description: Inbound/outbound payment methods supported by this account.
          properties:
            inbound:
              type:
                - array
                - 'null'
              items:
                $ref: '#/components/schemas/PaymentMethod'
              description: >-
                Inbound (deposit) payment methods this account supports. Array
                of `{name, status}` (see `PaymentMethod`), e.g. `[{name: "WIRE",
                status: "active"}, {name: "ACH", status: "active"}, {name:
                "WALLET", status: "active"}]` on a crypto virtual account.
                `status` is one of `active`, `coming-soon`, `disabled`.
            outbound:
              type:
                - array
                - 'null'
              items:
                $ref: '#/components/schemas/PaymentMethod'
              description: >-
                Outbound (payout) payment methods this account supports. Array
                of `{name, status}`, e.g. `[{name: "WIRE", status: "active"},
                {name: "ACH", status: "coming-soon"}]` on a crypto virtual
                account. `status` is one of `active`, `coming-soon`, `disabled`.
        methods:
          type:
            - object
            - 'null'
          description: Alias of `payment_methods` (same shape).
          properties:
            inbound:
              type:
                - array
                - 'null'
              items:
                $ref: '#/components/schemas/PaymentMethod'
              description: >-
                Alias of `payment_methods.inbound` — byte-identical value on the
                same VA fetch.
            outbound:
              type:
                - array
                - 'null'
              items:
                $ref: '#/components/schemas/PaymentMethod'
              description: >-
                Alias of `payment_methods.outbound` — byte-identical value on
                the same VA fetch.
        account_holder_name:
          type:
            - string
            - 'null'
          description: Flat bank detail projected from `source_deposit_instructions`.
        account_number:
          type:
            - string
            - 'null'
          description: >-
            Flat bank detail. `null` (or the ACT-only `"PENDING-ACT-ACCOUNT"`
            sentinel) until the account is provisioned.
        routing_number:
          type:
            - string
            - 'null'
          description: Flat bank detail projected from `source_deposit_instructions`.
        bank_name:
          type:
            - string
            - 'null'
          description: Flat bank detail projected from `source_deposit_instructions`.
        bank_address:
          type:
            - string
            - 'null'
          description: Flat bank detail projected from `source_deposit_instructions`.
        account_holder_address:
          type:
            - string
            - 'null'
          description: Flat bank detail projected from `source_deposit_instructions`.
        description:
          type: string
          description: Human-readable label set at creation.
        status_reason:
          type: string
          description: Human-readable reason backing the current status (e.g. RFI details).
        markup:
          type: object
          description: >-
            Markup configuration. Present only when fetching a single VA by ID —
            omitted from the list projection.
          additionalProperties: true
        created_at:
          type: string
          description: ISO 8601 timestamp.
        updated_at:
          type: string
          description: ISO 8601 timestamp.
        metadata:
          type: object
          description: Customer-attached Stripe-style key/value metadata.
          additionalProperties: true
      required:
        - id
        - user_id
        - status
        - type
        - mode
        - created_at
        - updated_at
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        statusCode:
          type: number
        error:
          type: string
        timestamp:
          type: string
        path:
          type: string
        details: {}
      required:
        - message
    PaymentMethod:
      type: object
      description: A single supported payment method on a virtual account.
      properties:
        name:
          type: string
          description: Method name (e.g. `WIRE`, `ACH`).
        status:
          type: string
          description: Method status (e.g. `active`).
      required:
        - name
        - status
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token from `POST /auth` (the `data.access_token` value).
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key issued by Kira. Required on every request, including `/auth`.

````