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

# The capability request object

> A request that one of your sub-clients be enabled for a capability, and where the review of it stands.

A capability request asks Kira to enable one of your sub-clients for something beyond its verification, such as paying on behalf of its own customers. The sub-client answers the capability's requirements through a link, and compliance reviews the answers.

A sub-client has at most one open request per capability.

## Example

```json theme={null}
{
  "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
}
```

## Fields

| Field | Type | Description |
| - | - | - |
| `id` | string, uuid | The request's identifier. |
| `user_id` | string, uuid | The sub-client the request is for. |
| `capability` | string | The capability requested. [Values](https://docs.kirafin.ai/reference/capabilities/values.md#capability) |
| `status` | string | Where the request stands. [Values](https://docs.kirafin.ai/reference/capabilities/values.md#request-status) |
| `requirements_version` | string | Identifies the list of requirements the request was opened against. It changes when that list changes. |
| `verification_link` | string, uri | The link where the sub-client answers the requirements. Only while `status` is `requested`. |
| `verification_link_expires_at` | string, date-time | When `verification_link` stops working, ISO 8601. |
| `evidence` | object | `answers_sha256` and `document_count` of what the sub-client sent, once Kira has kept a copy. The answers and files are never returned. |
| `review` | object | The latest review outcome: `answer`, plus `reject_type` and `labels` on a `RED`. Absent until compliance has reviewed the request. [Values](https://docs.kirafin.ai/reference/capabilities/values.md#review-answer) |
| `grant` | object | `event_uuid`, `status` and `created_at` of the capability the approval granted. Only on an `approved` request. [Values](https://docs.kirafin.ai/reference/capabilities/values.md#grant-status) |
| `cancel_reason` | string | Why the request was cancelled. Only on a `cancelled` request. [Values](https://docs.kirafin.ai/reference/capabilities/values.md#cancel_reason) |
| `created_at` | string, date-time | When the request was opened, ISO 8601. |
| `submitted_at` | string, date-time or `null` | When the sub-client sent its answers, ISO 8601. |
| `decided_at` | string, date-time or `null` | When the request was approved or rejected, ISO 8601. |

The fields that only apply at some stages are left out of the response, not sent as `null`.

## How a request is decided

1. [Request a capability](https://docs.kirafin.ai/api-reference/capabilities/request-a-capability.md) for a verified business sub-client. The request opens as `requested`, with a `verification_link`.
2. Send the sub-client to `verification_link`. The link lasts 30 days. Once it has expired, request the capability again: you get the same request back with a fresh link.
3. When the sub-client sends its answers, the request moves to `submitted` and compliance reviews it. Compliance may also open a [request for information](https://docs.kirafin.ai/compliance/rfi.md) about it.
4. The review ends one of three ways:
   * **Approved.** `status` becomes `approved` and `grant.status` is `granted`. The sub-client can use the capability.
   * **Sent back.** `status` returns to `requested` with `review.reject_type` `RETRY` and a new `verification_link`. The sub-client completes what was missing and sends it again.
   * **Rejected.** `status` becomes `rejected` with `review.reject_type` `FINAL`. You cannot request that capability for the sub-client again.

No webhook reports these moves. Read `status` with [Get a capability request](https://docs.kirafin.ai/api-reference/capabilities/get-a-capability-request.md), or many sub-clients at once with [List capability requests](https://docs.kirafin.ai/api-reference/capabilities/list-capability-requests.md) and `latest=true`.

A granted capability can be revoked later. `grant.status` then reads `revoked`, and the sub-client can no longer use it or request it again.


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