Skip to main content

KYC Verification via Redirect Integration

This guide describes a redirect-based integration of the hosted KYC (Know Your Customer) flow. Instead of embedding an IFrame, your application opens the flow in a new browser tab. When the user clicks Finish, they are redirected to the redirect URL configured on your integration in the dashboard, with the session id in the query parameters.

info

This guide uses the current KYC endpoints, under /v1/digital-onboarding. They replace the /sessions/start and /sessions/verdict endpoints, which are deprecated.


1. Start a KYC Session (from your backend)​

Start a session by sending a POST request from your backend. Never call this endpoint from the browser: your API key would be exposed to anyone visiting your page. Each session belongs to the integration of the API key, which defines the redirect URL, the webhook URL and the other settings.

POST https://authenticalls.com/kyc/client/api/v1/digital-onboarding/start
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>

Request Payload (JSON):

{
"country": "RO",
"type": "id-card",
"customerId": "customer-123",
"withLiveness": true,
"runNationalRegistryLookup": false,
"runDocumentProof": false
}
  • country (required): ISO alpha 2 code of the country that issued the document.
  • type (required): The type of the document the user will capture (e.g. id-card, passport, driving-license).
  • customerId (optional): Your internal identifier for the user, returned with the result.
  • withLiveness (optional, default false): Whether the user also takes liveness selfies, matched against the document photo.
  • runNationalRegistryLookup (optional, default false): Whether to also look the individual up in the national registry.
  • runDocumentProof (optional, default false): Whether to also run Document Proof (anti-spoofing) on the document images.

For the full schema, see the start session API reference. For the accepted country and document combinations, see All Countries.

Response (JSON):

{
"sessionId": "<SESSION_ID>"
}

Return the sessionId to your frontend. It is safe to expose: it only lets the user go through the flow, and does not give access to the result.


2. Open the Flow in a New Tab​

With the returned sessionId, build the flow URL and open it. Your integration already knows the redirect URL, so only the session id is needed.

// After obtaining sessionId from your backend:
const kycUrl =
`https://authenticalls.com/kyc/client/app/intro` + `?sessionId=${sessionId}`;

// Open in a new tab:
window.open(kycUrl, "_blank");

Call window.open directly from the user's click handler, or browsers may block the new tab as a popup. If you need to wait for your backend first, you can also redirect the current tab with location.href = kycUrl.

Query Parameters​

  • sessionId (required): The session identifier returned when starting the session.

Desktop users and the QR code

On desktop, the first screen offers the user to continue on their phone by scanning a QR code, or to continue on the current device. If they scan it, the desktop tab waits for the phone to finish, then shows the Finish button as usual.


3. Handle the Redirect​

When the KYC process ends, the flow shows a Finish button. Clicking it redirects the browser to the redirect URL configured on your integration, with the session id appended:

{redirect_url}?digitalOnboardingSessionId={sessionId}
  • digitalOnboardingSessionId: The KYC session id, which is also the key of its result.

The user is redirected both after a successful processing and after a failure, so always check the status of the result. Configure a redirect URL without query parameters of its own, since the session id is appended with ?.

Do not trust the query parameter alone: anyone can open your redirect URL with an arbitrary id. Use it to retrieve the result from your backend:

GET https://authenticalls.com/kyc/client/api/v1/digital-onboarding/result?digitalOnboardingSessionId=<SESSION_ID>
Authorization: Bearer <YOUR_API_KEY>

The result contains:

  • status: One of Completed, PartiallyCompleted (some of the operations failed and were refunded), Failed or Pending (not processed yet).
  • customerId: The identifier you sent when starting the session, if any. Use it to check that the session belongs to the user you expect.
  • The Document Analysis (the data extracted from the document) and, depending on the options the session was started with, the Face Match and the national registry lookup.

See the get result API reference for the response structure.


4. Basic Integration Flow​


5. Optional: Webhook Notification​

The redirect depends on the user clicking Finish: a user who closes the tab is never redirected. To be notified reliably, configure a webhook URL on your integration in the dashboard, and receive a server-side webhook as soon as a KYC session is processed. We recommend also generating a webhook secret, so the requests are signed and you can verify their signature.

Webhook Request:

POST {webhook_url}
Content-Type: application/json

Payload:

{
"id": "<WEBHOOK_EVENT_ID>",
"event": "digital_onboarding.completed",
"sandbox": false,
"data": {
"digitalOnboardingResult": {
"id": "<SESSION_ID>",
"status": "Completed",
"customerId": "customer-123"
// ...same structure as the get result response
},
"integration": {
// ...the integration the session belongs to
}
}
}

data.digitalOnboardingResult has the same structure as the get result response, so your backend can update the user's status or trigger downstream workflows directly from the webhook.

For integrations without a webhook secret, the fields under data are also duplicated at the top level of the payload. This is deprecated, and will be removed after January 31, 2027 (UTC). Read the event data from data.

Integration Flow with Webhook​