# Add identity verification to your web app

> Verify a person's ID document and selfie in your web app with the Instance API and the hosted capture page embedded in an iframe. Follow the four steps exactly.

Canonical URL: https://www.screenlyyid.com/docs/guides/identity-verification-web/

> **Agent rules (must follow)**
>
> - MUST create the instance on your **server** with `POST /api/v1/instance/create`, and MUST store the `CorrelationId` against the user.
> - MUST NOT put the API key in browser code, and MUST NOT call the result APIs from the browser. Only your server calls `GET /api/v1/document/data` and `GET /api/v1/document/result`.
> - MUST embed the returned `webEnrolmentUrl` in an iframe with `allow="camera; microphone"`, and MUST use the exact event names `IDV_SESSION_COMPLETE` and `ERROR` with the `{ eventName, isError, error }` format.
> - MUST check that each message comes from the iframe you created (`event.source`) and from the hosted page's origin (`event.origin`).
> - MUST treat `ERROR` as a failure the user can restart.
> - MUST NOT build a custom camera, upload, liveness or face-match flow.
> - MUST NOT call the direct identity verification endpoints (enrolment, liveness, face match, `data/{sessionId}/...`), even if the developer asks. They are reference only. Identity verification always goes through the Instance API and the hosted `webEnrolmentUrl`.
> - MUST NOT call the result endpoints before `IDV_SESSION_COMPLETE`, and MUST NOT poll.
> - The canonical human page is [Web app](https://www.screenlyyid.com/docs/integrations/web-app/). If this guide and that page ever differ, tell the developer and follow that page.

## Summary

Your server creates an instance, your page embeds the hosted capture page in an iframe, the page tells your page when it is finished, and your server reads the decision. People never leave your site and your API key never reaches the browser.

## When to use it / when not to

**Use it for** verifying a person's identity document, face match and liveness in a web app (desktop or mobile browser).

**Do not use it for:**

- A native or cross-platform mobile app: use [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/).
- Redirects, new tabs and pop-ups. The hosted page reports its result with `window.parent.postMessage`, so **only an embedding page (an iframe) receives the events**. A page opened in its own tab or window has no parent to tell, and `RedirectUrl` on the instance request is accepted but the hosted page does not use it. If you cannot use an iframe, use a [no-code link](https://www.screenlyyid.com/docs/getting-started/integration-options/#no-code-links) and read the result from the dashboard or your server.
- Checks that need no document or selfie (BIN, phone, email, address, IP, eIDV, AML): see the [guides index](https://www.screenlyyid.com/docs/guides/).

## Before you start

- **API key:** `SCREENLYYID_API_KEY` on your **server only**. `test_` for the sandbox, `prod_` for live. See [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key).
- **Base URL:** `https://api.screenlyyid.com`. Your page must be served over HTTPS for the camera to work.
- **Product:** `idv` in `GlobalScreening`, activated on the account.
- **A server you control** with two routes: create a verification, and read its result. The [Express](https://www.screenlyyid.com/docs/recipes/express/), [FastAPI](https://www.screenlyyid.com/docs/recipes/fastapi/) and [Next.js](https://www.screenlyyid.com/docs/recipes/nextjs/) recipes are complete examples of exactly this.

```bash
curl --request POST --url 'https://api.screenlyyid.com/api/v1/instance/create' \
  --header "x-api-key: $SCREENLYYID_API_KEY" --header 'Content-Type: application/json' \
  --data '{"GlobalScreening": ["idv"], "CustomerIntelligence": []}'
# { "CorrelationId": "...", "webEnrolmentUrl": "https://app.screenlyyid.com/idv/..." }
```

## Use it on its own or stacked

Identity verification can run on its own (`GlobalScreening: ["idv"]`) or in the same instance as other checks for the same customer, for example `["idv", "aml", "eidv1"]` for client onboarding. The capture flow does not change: the other checks are server calls that send the same `CorrelationId`. See [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/).

Document and selfie identity verification only goes through the Instance API and the hosted flow. The direct identity verification endpoints are reference only.

## Implementation steps

The same four steps as the [Mobile app](https://www.screenlyyid.com/docs/integrations/mobile-app/) page, in the same order.

### Step 1: Create an instance (server)
```javascript
// server route: POST /api/verifications  (Node 18+)
const r = await fetch("https://api.screenlyyid.com/api/v1/instance/create", {
  method: "POST",
  headers: { "x-api-key": process.env.SCREENLYYID_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ GlobalScreening: ["idv"], CustomerIntelligence: [] }),
});
if (!r.ok) throw new Error(`instance/create failed (HTTP ${r.status})`);
const { CorrelationId, webEnrolmentUrl } = await r.json(); // names are exactly these
// save CorrelationId against the user; return { verificationId, webEnrolmentUrl } to the browser
```

### Step 2: Embed the page (browser)
```html
<iframe id="screenlyyid" src="WEB_ENROLMENT_URL" allow="camera; microphone"
        style="width:100%;height:700px;border:0" title="Identity verification"></iframe>
```

`allow="camera; microphone"` is required because the page is on another origin. Add `?skipIntro=true` to the URL to go straight to capture.

### Step 3: Listen for events (browser)
```javascript
window.addEventListener("message", async (event) => {
  const frame = document.getElementById("screenlyyid");
  if (!frame || event.source !== frame.contentWindow) return;   // only the iframe we created
  if (event.origin !== new URL(frame.src).origin) return;      // and only the hosted page's origin

  const { eventName, isError, error } = event.data || {};
  if (eventName === "IDV_SESSION_COMPLETE" && !isError) {
    frame.remove();
    const r = await fetch(`/api/verifications/${verificationId}`); // YOUR server, Step 4
    showOutcome(await r.json());
  } else if (eventName === "ERROR") {
    frame.remove();
    offerRestart(error);           // create a new instance and embed the new webEnrolmentUrl
  }
});
```

| Event | Meaning | What to do |
|---|---|---|
| `IDV_SESSION_COMPLETE` | The document and selfie have been processed and the results are stored. | Remove the iframe and ask your server for the result. |
| `ERROR` (`isError` is `true`) | A fatal error while processing the images. | Offer to restart with a new instance. |

### Step 4: Get the result (server)
```javascript
// server route: GET /api/verifications/:id  (check the verification belongs to the signed-in user first)
const headers = { "x-api-key": process.env.SCREENLYYID_API_KEY, "x-correlation-id": correlationId };
const [data, result] = await Promise.all([
  fetch("https://api.screenlyyid.com/api/v1/document/data", { headers }).then((r) => r.json()),
  fetch("https://api.screenlyyid.com/api/v1/document/result", { headers }).then((r) => r.json()),
]);
```

Call once, after the event. A `500 internal_error` means you called before the capture finished.

## Desktop browsers: continue on a phone

On a desktop browser the hosted page first shows a QR code. The person scans it with their phone, captures their ID document and selfie there, and the page in your iframe shows their progress. When the phone finishes, your page receives the same message as for an on-device capture: `IDV_SESSION_COMPLETE`, or `ERROR` if the capture failed. Nothing changes in your code: keep listening for the same events and read the result from your server once.

- The page offers **Use this device instead** for people who want to capture on the desktop (the iframe then needs `allow="camera; microphone"` as above).
- To skip the QR code and go straight to on-device capture, add `handoff=off` to the `webEnrolmentUrl`, for example `...?skipIntro=true&handoff=off`.
- Keep the iframe open while the person finishes on their phone. The link belongs to one verification: once it has finished, the QR screen reports that the link can't be continued.
- Phones, tablets and mobile WebViews never see the QR code, so the [mobile guide](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/) is unchanged.

## Reading the result

The same as in the [mobile guide](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/#result): `Decision.Level` (`HIGH`, `MEDIUM`, `LOW`), `LivenessResult.Result` (`Live` or `Not Live`) and `FaceMatchResult.IsMatch`. See [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/).

### Decision logic

`HIGH` with a live selfie that matches the ID is approved; `LOW`, a failed liveness check or a face mismatch is rejected; anything else (`MEDIUM`) needs review.

```javascript
function nextStep(result) {
  const level = result.Decision.Level;
  const live = result.LivenessResult.Result === "Live";
  const match = result.FaceMatchResult.IsMatch;
  if (level === "HIGH" && live && match) return "approved";
  if (level === "LOW" || !live || !match) return "rejected";
  return "needs_review"; // MEDIUM
}
```

## Errors and limits

| Status | When | Body |
|---|---|---|
| `400` | `instance/create`: a product code that does not exist or is not activated. Result endpoints: no `x-correlation-id` header. | Problem-details JSON, or `{"error": "correlation_id_required"}` |
| `401` | Missing or invalid `x-api-key` | Problem-details JSON |
| `500` | Result endpoints before the capture finished, or an unknown `CorrelationId` | `{"error": "internal_error", "message": "An unexpected error occurred"}` |

No rate limit is documented for these calls.

## Test it

With a `test_` key, create a verification and confirm the response has `CorrelationId` and `webEnrolmentUrl`, and that the hosted page loads in the iframe with the camera prompt. **A real capture needs a camera and an ID document**: complete one in a browser to see `IDV_SESSION_COMPLETE` arrive and your server read the result.

## Done when

- [ ] The instance is created on the server, the `CorrelationId` is stored per user, and the API key never reaches the browser
- [ ] The `webEnrolmentUrl` is embedded in an iframe with `allow="camera; microphone"` over HTTPS
- [ ] The message handler checks `event.source` and `event.origin`, and handles `IDV_SESSION_COMPLETE` and `ERROR` (exact names) once, including when the person finishes on their phone (the iframe stays open until then)
- [ ] On `IDV_SESSION_COMPLETE` the server (not the browser) calls `document/data` and `document/result` once with `x-api-key` and `x-correlation-id`
- [ ] `HIGH`, `MEDIUM` and `LOW` lead to approved, review and rejected, and `ERROR` restarts the flow
- [ ] A verification belongs to one user: another user's id returns 404
- [ ] Verified in a browser with a `test_` key

## Related

- [Web app](https://www.screenlyyid.com/docs/integrations/web-app/) (canonical human page)
- [Identity verification (mobile)](https://www.screenlyyid.com/docs/guides/identity-verification-mobile/)
- [Get hosted SDK document data](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-document-data/), [Get hosted SDK decision result](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/)
- [Instance API](https://www.screenlyyid.com/docs/authentication/create-instance/), [Understanding results](https://www.screenlyyid.com/docs/data/understanding-results/), [Run several checks in one session](https://www.screenlyyid.com/docs/guides/stacking-checks/)
