# 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](https://developer.incode.com/docs/workflows-20))
* 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](https://developer.incode.com/docs/single-onboarding) endpoint from your backend:

```javascript
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](https://developer.incode.com/docs/onboarding-session-lifecycle).

## Retrieving results

Once the session is complete, retrieve results via:

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