> ## 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.

# Request a capability

> Ask for one of your sub-clients to be enabled for a capability, and get back the link where the sub-client answers its requirements. [How a request is decided](/reference/capabilities/the-capability-request-object#how-a-request-is-decided) says what happens next.

Calling it again for the same sub-client and capability is safe. While the request still waits on the sub-client, you get the same request back with `200`, and with a fresh `verification_link` once the earlier one has expired.



## OpenAPI

````yaml /openapi/kira-api.2026-04-14.json post /v1/capability-requests
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 except the token call needs a bearer
    access token (see Authentication). Pin your account to the recommended
    version before integrating (see [Versioning](/using-the-api/versioning)).
  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: []
tags:
  - name: Authentication
  - name: Versioning
  - name: Users
  - name: Virtual Accounts
  - name: Recipients
  - name: Quotations
  - name: Payouts
  - name: Ultimate Payors
  - name: Capabilities
  - name: Reference
  - name: RFIs
paths:
  /v1/capability-requests:
    post:
      tags:
        - Capabilities
      summary: Request a capability
      description: >-
        Ask for one of your sub-clients to be enabled for a capability, and get
        back the link where the sub-client answers its requirements. [How a
        request is
        decided](/reference/capabilities/the-capability-request-object#how-a-request-is-decided)
        says what happens next.


        Calling it again for the same sub-client and capability is safe. While
        the request still waits on the sub-client, you get the same request back
        with `200`, and with a fresh `verification_link` once the earlier one
        has expired.
      operationId: post_v1-capability-requests
      parameters:
        - in: header
          name: X-Api-Version
          required: false
          description: >-
            Version applied to this request. It wins over your account's pinned
            version — see [Versioning](/using-the-api/versioning).
          schema:
            type: string
            example: '2026-04-14'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCapabilityRequestRequest'
            example:
              user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
              capability: pobo
      responses:
        '200':
          description: >-
            The sub-client already had a request open for this capability, still
            waiting on it. This is that request, with a link that has not
            expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilityRequest'
              example:
                id: 5d2e8f14-7a3b-4c6d-9e1f-2a3b4c5d6e7f
                user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
                capability: pobo
                status: requested
                requirements_version: 850f14
                verification_link: https://identity.example.com/websdk/p/aGVsbG8tdGhlcmU
                verification_link_expires_at: '2026-11-14T14:03:22.418Z'
                created_at: '2026-10-15T14:03:22.418Z'
                submitted_at: null
                decided_at: null
        '201':
          description: >-
            A new request was opened. Send the sub-client to
            `verification_link`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilityRequest'
              example:
                id: 5d2e8f14-7a3b-4c6d-9e1f-2a3b4c5d6e7f
                user_id: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
                capability: pobo
                status: requested
                requirements_version: 850f14
                verification_link: https://identity.example.com/websdk/p/aGVsbG8tdGhlcmU
                verification_link_expires_at: '2026-11-14T14:03:22.418Z'
                created_at: '2026-10-15T14:03:22.418Z'
                submitted_at: null
                decided_at: null
        '400':
          description: >-
            A field is missing or invalid. `details` holds one entry per
            problem.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapabilityRequestBodyValidationError'
              example:
                code: validation_error
                error: Invalid data
                details:
                  - message: user_id is Invalid uuid
                  - message: capability is Required
        '401':
          description: >-
            No valid bearer token came with the request. Get one from [Get
            access token](/api-reference/authentication/get-access-token) and
            send it as `Authorization: Bearer <token>`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: invalid_request
                message: >-
                  The request was not authenticated. Request a token at POST
                  /auth with your Client ID and your API key, then send it as
                  Authorization: Bearer <token>.
        '403':
          description: Your API key's role does not allow writing sub-clients.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 403
                error: Forbidden
                message: This API key does not allow this action
                timestamp: '2026-10-15T14:03:22.418Z'
                path: /v1/capability-requests
        '404':
          description: >-
            No sub-client of yours has that `user_id`. The same body comes back
            whether the sub-client does not exist or belongs to another client.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 404
                error: Not Found
                message: Not found
                timestamp: '2026-10-15T14:03:22.418Z'
                path: /v1/capability-requests
                code: not_found
        '409':
          description: >-
            The sub-client cannot get a new request for this capability. Read
            `code`.


            A sub-client that was not verified through a route that can collect
            the requirements is refused with a `409` too. Its `message` reads
            `this subclient was not verified through a route that can collect
            the requirements`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                capability_already_granted:
                  summary: The sub-client already holds the capability
                  value:
                    statusCode: 409
                    error: Conflict
                    message: this subclient already holds this capability
                    timestamp: '2026-10-15T14:03:22.418Z'
                    path: /v1/capability-requests
                    code: capability_already_granted
                capability_closed:
                  summary: The capability was refused for this sub-client
                  value:
                    statusCode: 409
                    error: Conflict
                    message: this capability was refused for this subclient
                    timestamp: '2026-10-15T14:03:22.418Z'
                    path: /v1/capability-requests
                    code: capability_closed
                request_already_open:
                  summary: The sub-client submitted a request that is still in review
                  value:
                    statusCode: 409
                    error: Conflict
                    message: a request for this capability is already open
                    timestamp: '2026-10-15T14:03:22.418Z'
                    path: /v1/capability-requests
                    code: request_already_open
        '422':
          description: The capability cannot be requested for this sub-client. Read `code`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                capability_unknown:
                  summary: No capability has that code
                  value:
                    statusCode: 422
                    error: Unprocessable Entity
                    message: unknown capability 'teleportation'
                    timestamp: '2026-10-15T14:03:22.418Z'
                    path: /v1/capability-requests
                    code: capability_unknown
                capability_not_requestable:
                  summary: A bank is set on the user, not requested
                  value:
                    statusCode: 422
                    error: Unprocessable Entity
                    message: >-
                      'jp_morgan' is declared on the subclient, not requested
                      here
                    timestamp: '2026-10-15T14:03:22.418Z'
                    path: /v1/capability-requests
                    code: capability_not_requestable
                user_not_eligible:
                  summary: The sub-client is not verified yet
                  value:
                    statusCode: 422
                    error: Unprocessable Entity
                    message: >-
                      Payments on behalf of is available to subclients in status
                      VERIFIED
                    timestamp: '2026-10-15T14:03:22.418Z'
                    path: /v1/capability-requests
                    code: user_not_eligible
        '500':
          description: >-
            Something failed on our side. Retry, and if it keeps happening
            contact your Kira contact with the time of the call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                message: Internal server error
        '503':
          description: >-
            The link could not be created. Nothing was left open, so send the
            same call again after a short wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 503
                error: Service Unavailable
                message: the verification link could not be created; try again shortly
                timestamp: '2026-10-15T14:03:22.418Z'
                path: /v1/capability-requests
                code: provider_unavailable
      security:
        - bearerAuth: []
          apiKeyAuth: []
      servers:
        - url: https://api.balampay.com/sandbox
          description: Sandbox
        - url: https://api.balampay.com
          description: Production
components:
  schemas:
    CreateCapabilityRequestRequest:
      type: object
      required:
        - user_id
        - capability
      properties:
        user_id:
          type: string
          format: uuid
          description: |-
            The sub-client to enable.

            It has to be a business, verified (`status` `VERIFIED`).
          example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
        capability:
          type: string
          enum:
            - pobo
          description: >-
            The capability to request — see
            [Values](/reference/capabilities/values#capability).
          example: pobo
    CapabilityRequest:
      type: object
      description: >-
        A request that a sub-client be enabled for a capability — see [The
        capability request
        object](/reference/capabilities/the-capability-request-object).
      properties:
        id:
          type: string
          format: uuid
          description: The request's identifier.
        user_id:
          type: string
          format: uuid
          description: The sub-client the request is for.
        capability:
          type: string
          description: >-
            The capability requested — see
            [Values](/reference/capabilities/values#capability).
        status:
          type: string
          description: >-
            Where the request stands. Available options: `requested`,
            `submitted`, `approved`, `rejected`, `cancelled` — see
            [Values](/reference/capabilities/values#request-status).
        requirements_version:
          type: string
          description: >-
            Identifies the list of requirements the request was opened against.
            It changes when that list changes.
        verification_link:
          type: string
          format: uri
          description: |-
            The link where the sub-client answers the requirements.

            Only while `status` is `requested`.
        verification_link_expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When `verification_link` stops working, ISO 8601. Request the
            capability again with [Request a
            capability](/api-reference/capabilities/request-a-capability) for a
            fresh link.
        evidence:
          type: object
          description: >-
            What the sub-client sent, once Kira has kept a copy of it. The
            answers and files themselves are never returned.
          properties:
            answers_sha256:
              type:
                - string
                - 'null'
              description: SHA-256 of the answers, to tell one submission from another.
            document_count:
              type: integer
              description: How many files the sub-client attached.
        review:
          type: object
          description: >-
            The latest review outcome. Absent until compliance has reviewed the
            request.
          properties:
            answer:
              type: string
              description: >-
                Available options: `GREEN`, `RED` — see
                [Values](/reference/capabilities/values#review-answer).
            reject_type:
              type: string
              description: >-
                On a `RED` answer. Available options: `RETRY`, `FINAL` — see
                [Values](/reference/capabilities/values#review-reject_type).
            labels:
              type: array
              description: Codes naming what the review found, when it named any.
              items:
                type: string
        grant:
          type: object
          description: The capability the approval granted. Only on an `approved` request.
          properties:
            event_uuid:
              type: string
              format: uuid
              description: The grant's identifier.
            status:
              type: string
              description: >-
                Whether the sub-client still holds the capability. Available
                options: `granted`, `revoked` — see
                [Values](/reference/capabilities/values#grant-status).
            created_at:
              type: string
              format: date-time
              description: When the grant reached this status, ISO 8601.
        cancel_reason:
          type: string
          description: >-
            Why the request was cancelled. Only on a `cancelled` request — see
            [Values](/reference/capabilities/values#cancel_reason).
        created_at:
          type: string
          format: date-time
          description: When the request was opened, ISO 8601.
        submitted_at:
          type:
            - string
            - 'null'
          format: date-time
          description: When the sub-client sent its answers, ISO 8601. `null` until then.
        decided_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            When the request was approved or rejected, ISO 8601. `null` until
            then.
    CapabilityRequestBodyValidationError:
      type: object
      properties:
        code:
          type: string
          description: Always `validation_error`.
        error:
          type: string
          description: Always `Invalid data`.
        details:
          type: array
          description: One entry per problem.
          items:
            type: object
            properties:
              message:
                type: string
                description: The field and what is wrong with it.
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        The `data.access_token` value from [Get access
        token](/api-reference/authentication/get-access-token).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.