iFrame

The iFrame integration embeds the Incode-hosted verification flow inside your own web page using an HTML <iframe> element. Your users complete identity verification without leaving your domain, while Incode manages the verification UI and infrastructure.

This approach requires a backend to start sessions and a small amount of front-end code to embed and communicate with the iframe.

How it works

1. Your backend starts an onboarding session and generates a session URL.
2. Your front end renders an <iframe> pointing to that URL.
3. The user completes identity verification inside the iframe, on your page.
4. Your app listens for a postMessage event from the iframe to detect session completion, then retrieves results via webhook or API.

Prerequisites

• An active Incode Omni account with API credentials
• A configured Workflow in Dashboard (see Workflows)
• A backend service to call the Incode Omni API and start sessions
• HTTPS on your domain (required for camera and microphone access)

Starting a session

Call the Start Onboarding Session endpoint from your backend:

POST /omni/start

Include an externalCustomerId to link the session to a user in your system. The response includes a session token and an onboarding URL. Pass the URL to your front end to use as the src of your iframe.

Embedding the iframe

<iframe
  src="https://YOUR_ONBOARDING_URL"
  allow="camera; microphone; geolocation"
  width="100%"
  height="700px"
  frameborder="0"
> </iframe>

The allow attribute is required. Without camera and microphone permissions explicitly granted, the browser will block the iframe from accessing device hardware, and the verification flow will fail.

Detecting session completion

Listen for a postMessage event from the iframe to know when the user has finished:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'ONBOARDING_FINISHED') {
    // Session complete — fetch results or redirect the user
  }
});

For a full list of event types, see the Onboarding Session Lifecycle.

Retrieving results

Once the session is complete, retrieve results via:

• Webhook: Configure an Onboarding Status Webhook or Session Webhooks to receive real-time notifications
• API: Call How to Fetch Results and Data endpoints directly from your backend

When to use this approach

The iFrame approach is a good fit when:

• You want users to stay on your domain throughout the verification process
• You have a backend but want to minimize front-end development
• You don't need to customize the verification UI

If you need users to complete verification on a separate page, consider Redirect URL instead. If you need full UI control, see Web SDK.