---
title: "iFrame"
url: "https://developer.incode.com/integrate-by-platform/web-integrations-iframe/"
section: "integrate-by-platform"
group: "Web Integration Overview"
version: "v1.1"
status: "live"
---
# 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](/dashboard-platform-administration/workflows-20/) 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](/integrate-by-platform/single-onboarding/) 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

```html
<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:

```jsx
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](/get-started-with-incode/onboarding-session-lifecycle/).

## Retrieving results

Once the session is complete, retrieve results via:

- **Webhook**: Configure an [Onboarding Status Webhook](/general-reference/onboarding-status-webhook/) or [Session Webhooks](/general-reference/session-webhooks/) to receive real-time notifications
- **API**: Call [How to Fetch Results and Data](/integrate-by-platform/how-to-fetch-onboarding-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](/integrate-by-platform/web-integrations-redirect-url/) instead. If you need full UI control, see [Web SDK](/integrate-by-platform/web-integrations-websdk/).