> For the complete documentation index, see [llms.txt](https://finext.gitbook.io/one-kyc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://finext.gitbook.io/one-kyc/api/verification-links.md).

# Verification links

Verification links are single-use or time-limited URLs through which a user starts verification. You create links through the Tenant API or the admin panel and deliver them to the user (by email, SMS, QR code, or in your customer portal). When the user opens the link, a verification session is automatically created or attached, and the user is redirected to the OneKYC verification page.

## Create a verification link

<mark style="color:green;">`POST`</mark> `undefined/v1/kyc/verification-links`

### Legacy compatibility

The canonical KYC path is `/tenant/v1/kyc/verification-links`. For existing tenant integrations, OneKYC also intentionally keeps `/tenant/v1/verification-links` and `/tenant/v1/verificationLinks` as KYC aliases. Verification-link create and batch-create request bodies also accept legacy field aliases with different casing or separators, such as `flowId`, `FlowID`, `externalUserId`, `redirectUrl`, and `prefilledData`.

Do not treat these aliases as dead code. They are a supported compatibility contract and may be removed only after a separately versioned Tenant API deprecation and migration window.

## Batch create links

Creates several verification links in a single request.

<mark style="color:green;">`POST`</mark> `undefined/v1/kyc/verification-links/batch`

## List links

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyc/verification-links`

## Get a link by ID

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyc/verification-links/{id}`

## Revoke a link

A revoked link becomes invalid and cannot be used to start verification.

<mark style="color:green;">`POST`</mark> `undefined/v1/kyc/verification-links/{id}/revoke`

## Get a QR code

Returns the QR code for a verification link. Use it for the cross-device flow: the user scans the QR code on a mobile device and continues verification there.

<mark style="color:blue;">`GET`</mark> `undefined/v1/kyc/verification-links/{id}/qr`

***

## Link lifecycle

```
[Created] → [Activated] → [Consumed]
    ↓            ↓            ↓
[Expired]   [Expired]   [Completed]
    ↓            ↓
[Revoked]   [Revoked]
```

**Link statuses:**

| Status      | Description                                                                     |
| ----------- | ------------------------------------------------------------------------------- |
| `active`    | Link created; the user has not opened it yet                                    |
| `activated` | The user opened the link; a session was created and verification is in progress |
| `consumed`  | Verification completed (approved, rejected, or routed to review)                |
| `expired`   | The link's TTL (`ttl_seconds`) elapsed; the link is no longer usable            |
| `revoked`   | The link was revoked manually through the API or the admin panel                |

> **Note.** After creating the link, deliver it to the user (by email, SMS, or QR code). Opening the link automatically creates a verification session. For the cross-device flow, use the QR code (`GET /v1/kyc/verification-links/{id}/qr`).

***

## Redirect after verification completes

When you create a link, you can pass the **redirect\_url** parameter — the URL the user is redirected to once verification completes (for example, a customer portal or an application form).

### How it works

1. **When creating the link**, pass `redirect_url` in the request body (`POST /v1/kyc/verification-links` or batch).
2. **On activation**, `redirect_url` is stored in the session and returned in the activation response (the `redirect_url` field).
3. **On the completion screen** (after approval, rejection, or routing to review) the user sees:
   * a **return button** — the user clicks it and is redirected to `redirect_url`; or
   * an **automatic redirect** after a configured delay.

### Configuring behaviour

Redirect behaviour is set in the **flow parameters** in the admin panel:

* **Redirect behaviour on completion** — redirect mode: "Show button" or "Auto redirect".
* **Redirect delay (seconds)** — delay before the automatic redirect (applies when "Auto redirect" is selected).

Defaults: button is shown; automatic mode delay is 3 seconds. For details, see [Flows (admin)](/one-kyc/admin/flows.md#redirect-settings).