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 account with API credentials
• A configured Workflow in Dashboard
• 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; accelerometer; gyroscope"
  width="100%"
  height="700px"
  frameborder="0"
> </iframe>

If you create the iFrame with JavaScript, set the same permissions:

frame.setAttribute("allow", "camera; microphone; geolocation; accelerometer; gyroscope");

The allow attribute is required. The browser blocks an embedded iFrame from using device hardware and sensors unless each permission is explicitly granted:

• camera and microphone: Required for ID and selfie capture.
• accelerometer and gyroscope: Required for ID capture on Chrome for Android. Without them, Chrome silently blocks the motion sensors the SDK uses, and ID capture stays on the loading screen.
• geolocation: Required to collect location signals.

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.