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
POST 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.
POST undefined/v1/kyc/verification-links/batch
List links
GET undefined/v1/kyc/verification-links
Get a link by ID
GET undefined/v1/kyc/verification-links/{id}
Revoke a link
A revoked link becomes invalid and cannot be used to start verification.
POST 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.
GET undefined/v1/kyc/verification-links/{id}/qr
Link lifecycle
Link statuses:
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
When creating the link, pass
redirect_urlin the request body (POST /v1/kyc/verification-linksor batch).On activation,
redirect_urlis stored in the session and returned in the activation response (theredirect_urlfield).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; oran 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).
Last updated