Skip to main content

KYC Verification via IFrame Integration

This guide shows how to embed the hosted KYC (Know Your Customer) flow in your website with an IFrame. It covers starting a session, embedding the IFrame, reacting to the completion message sent through postMessage, and retrieving the result.

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.

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. Embed the IFrame​

Add the IFrame to your page. The allow="camera; microphone" attribute is required, since the user captures their document (and selfies) with the camera.

<iframe
id="kycFrame"
allow="camera; microphone"
style="max-width: 639px; min-height: 600px;"
></iframe>

The iframe's maximum suggested width is 639px and minimum height 600px.

Responsive styling for mobile

To make the IFrame take the full screen on mobile devices, add the following CSS:

/* Desktop default */
#kycFrame {
width: 100%;
max-width: 639px;
min-height: 600px;
}

/* Mobile full screen */
@media (max-width: 768px) {
#kycFrame {
width: 100vw !important;
height: 100svh !important;
max-width: none;
border: none;
position: fixed;
top: 0;
left: 0;
z-index: 9999;
}
}

Once your frontend has the sessionId, set the IFrame's src:

// After obtaining sessionId from your backend:
const integratorOrigin = encodeURIComponent(location.origin);
document.getElementById("kycFrame").src =
`https://authenticalls.com/kyc/client/app/intro` +
`?sessionId=${sessionId}` +
`&iframe` +
`&integrator=${integratorOrigin}`;

Query Parameters

  • sessionId (required): The session identifier returned when starting the session.
  • iframe (flag): When present, the app renders in IFrame mode.
  • integrator (required with iframe): The URL-encoded origin of your website (e.g. https://yourapp.com). The completion message is only sent to this origin.

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, keep the IFrame open: it waits for the phone to finish, then sends the completion message as usual.


3. Handle the Completion Message with postMessage​

When the KYC process completes, the IFrame sends a message to the parent window:

window.addEventListener("message", async (event) => {
// 1. Only accept messages from our origin
if (event.origin !== "https://authenticalls.com") return;

// 2. Only handle the KYC completion message
if (event.data?.type !== "digital_onboarding_finished") return;

const { id, status } = event.data.payload;

// 3. Optional: hide the IFrame before it shows its own result screen
document.getElementById("kycFrame").style.display = "none";

// 4. Ask your backend to retrieve the full result (see step 4)
await fetch(`/api/kyc/${id}/result`);
});

The message has the following shape:

{
"type": "digital_onboarding_finished",
"payload": {
"id": "<SESSION_ID>",
"status": "Completed"
}
}
  • id: The KYC session id, which is also the key of its result.
  • status: One of Completed, PartiallyCompleted (some of the operations failed and were refunded) or Failed.

Important Notes

  • The message does not contain the result. It only carries the session id and status, since the result holds the user's document data. Retrieve the result from your backend (step 4), and do not base any decision on the message alone: anyone can open your page and send messages to it.
  • Origin check: Always verify that event.origin is https://authenticalls.com.
  • Hiding the IFrame: The IFrame waits about 1 second after sending the message before showing its own result screen. Use that time to hide it if you want to show your own UI instead.
  • Failures: When the processing fails on the same device, the IFrame shows an error screen and no message is sent. Use the webhook as the reliable completion signal on your backend.

4. Retrieve the Result (from your backend)​

Use the session id to retrieve the full result with your API key:

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

The result contains the status, the optional customerId, 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.


5. Optional: Webhook Notification​

You can also receive a server-side webhook when a KYC session is processed. Configure your webhook URL on your integration in the dashboard. We recommend also generating a webhook secret, so the requests are signed and you can verify their signature.

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 you can process the result 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.


Full Integration Flow​

  1. Your backend starts a session with POST /v1/digital-onboarding/start and returns the sessionId to your frontend.
  2. Your frontend shows the IFrame, with sessionId, iframe and integrator in its src.
  3. The user captures their document (and selfies, with withLiveness) in the IFrame, on the same device or on their phone through the QR code.
  4. The IFrame posts a digital_onboarding_finished message to your page.
  5. Your page validates the message origin and type, hides the IFrame, and asks your backend for the result.
  6. Your backend retrieves the result with GET /v1/digital-onboarding/result, or processes the digital_onboarding.completed webhook.