> ## 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 liveness verification link > Issue hosted liveness-check link(s) for a user. Liveness cannot be performed through an API upload — it needs an interactive session — so relay each returned link to the right end user. Returns one link for an individual user and one link per beneficial owner for a business; each entry is tagged with `subject` (and, for a beneficial owner, `person_reference_id` and `name`) so you can route it. The request body is optional; supply `redirect` to send the user back to your own page after the session (see below). Calling this again for a subject whose link is still active returns that same link rather than issuing a new one — unless you supply a **different** `redirect`, which mints a fresh link. Completion is reported per link via the `user.liveness_completed` webhook and, on approval, a verification report is attached to the user. A liveness result never changes the user's `status`. **The redirect landing is a UX convenience, not the result** — always treat the `user.liveness_completed` webhook as the source of truth, since a session can still be held or expire after the user sees a success page. {/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */} Stable since **2025-01-01** — unchanged in **2026-06-01**. {/* version-stamp:end */} ## OpenAPI ````yaml /openapi/kira-api.2026-06-01.json post /v1/users/{user_id}/liveness-link openapi: 3.1.0 info: title: Kira API version: '2026-06-01' 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 - name: RFIs paths: /v1/users/{user_id}/liveness-link: post: tags: - Users summary: Request a liveness verification link description: >- Issue hosted liveness-check link(s) for a user. Liveness cannot be performed through an API upload — it needs an interactive session — so relay each returned link to the right end user. Returns one link for an individual user and one link per beneficial owner for a business; each entry is tagged with `subject` (and, for a beneficial owner, `person_reference_id` and `name`) so you can route it. The request body is optional; supply `redirect` to send the user back to your own page after the session (see below). Calling this again for a subject whose link is still active returns that same link rather than issuing a new one — unless you supply a **different** `redirect`, which mints a fresh link. Completion is reported per link via the `user.liveness_completed` webhook and, on approval, a verification report is attached to the user. A liveness result never changes the user's `status`. **The redirect landing is a UX convenience, not the result** — always treat the `user.liveness_completed` webhook as the source of truth, since a session can still be held or expire after the user sees a success page. operationId: post_v1-users-user-id-liveness-link parameters: - in: path name: user_id required: true schema: type: string format: uuid description: User UUID. - 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-06-01' requestBody: required: false content: application/json: schema: type: object properties: redirect: type: object description: >- Optional. Where to send the user after the hosted session, instead of the default completion screen. **Opt-in per client:** each URL must be HTTPS and its host must be on your redirect allowlist; an unlisted or non-HTTPS URL is rejected with `422`. **The allowlist is configured by the Kira team — there is no API or dashboard for it:** email support@kirafin.ai with the domains you want allowlisted (subdomain matches are allowed) and the environments they apply to. Until they are registered, any request carrying a `redirect` returns `422`. Omit to keep the default completion screen. Bound to the link when it is issued — a repeat call with a different `redirect` mints a new link. properties: success_url: type: string format: uri description: >- HTTPS URL the user is sent to after a successful session. **Required whenever `redirect` is present** — a `redirect` with only `reject_url` is rejected with `422`. example: https://app.example.com/kyc/done reject_url: type: string format: uri description: >- HTTPS URL the user is sent to after a rejected or abandoned session. Optional, but if you send the field it must be a valid allowlisted HTTPS URL — an empty value is `422`, not "omitted". example: https://app.example.com/kyc/failed responses: '200': description: Liveness link(s) issued — one entry per subject. content: application/json: schema: type: object properties: links: type: array description: >- One entry for an individual user, one per beneficial owner for a business. items: type: object properties: subject: type: string enum: - user - ubo description: >- `user` for an individual, `ubo` for a business's beneficial owner. person_reference_id: type: string description: >- Present for `ubo` subjects — identifies which beneficial owner this link is for; echoed back on the `user.liveness_completed` webhook. name: type: string description: >- Present for `ubo` subjects — the beneficial owner's name, to help you route the link. liveness_link: type: string format: uri description: >- Hosted URL to send this subject — opening it starts the interactive liveness session. Valid until `expires_at`. expires_at: type: string format: date-time description: >- When this link stops working — 7 days after issuance. Request the endpoint again after it expires to get a fresh one. example: links: - subject: user liveness_link: https://kyc.example.com/websdk/... expires_at: '2026-01-16T20:30:00.000Z' '400': description: >- The request body contains unexpected fields — this endpoint takes no body. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- User not found, or the liveness feature is not enabled for your account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- No verification is in progress to attach a liveness check to, or the identity provider doesn't support liveness for this subject. For an individual, this means no verification has started yet. For a business, its KYB has not been submitted, or it has no beneficial owners on record. Links are issuable once a business's KYB is submitted — it need not be fully verified first. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] apiKeyAuth: [] components: schemas: ValidationErrorResponse: type: object description: >- Validation / request error. The body shape is **not uniform** across the API — it varies by endpoint and by which validation layer rejects the request. The fields below are the union of what may appear; treat them all as optional. Observed shapes include `{ code, message }`, `{ code, message, errors[] }`, `{ code, error, details[] }`, `{ error, details[] }`, and a nested `{ error: { code, message, details } }`. Always branch on the HTTP status, not on a fixed body shape. properties: code: type: string message: type: string error: type: - string - object description: >- A short error label (e.g. `"Invalid data"`), or on some endpoints a nested `{ code, message, details }` object. errors: type: array items: type: object properties: field: type: string message: type: string required: - field - message details: type: - array - object description: >- Per-issue detail. Shape varies by endpoint — typically an array of `{ message }` or `{ path, message, code }`, occasionally an object. 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: 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`. ````