Add identity verification to your web app
Agent rules (must follow)
- MUST create the instance on your server with
POST /api/v1/instance/create, and MUST store theCorrelationIdagainst 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/dataandGET /api/v1/document/result. - MUST embed the returned
webEnrolmentUrlin an iframe withallow="camera; microphone", and MUST use the exact event namesIDV_SESSION_COMPLETEandERRORwith 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
ERRORas 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 hostedwebEnrolmentUrl. - MUST NOT call the result endpoints before
IDV_SESSION_COMPLETE, and MUST NOT poll. - The canonical human page is 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).
- 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, andRedirectUrlon the instance request is accepted but the hosted page does not use it. If you cannot use an iframe, use a no-code link 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.
Before you start#
- API key:
SCREENLYYID_API_KEYon your server only.test_for the sandbox,prod_for live. See Get a test key. - Base URL:
https://api.screenlyyid.com. Your page must be served over HTTPS for the camera to work. - Product:
idvinGlobalScreening, activated on the account. - A server you control with two routes: create a verification, and read its result. The Express, FastAPI and Next.js recipes are complete examples of exactly this.
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.
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 page, in the same order.
Step 1: Create an instance (server)#
// 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 browserStep 2: Embed the page (browser)#
<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)#
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)#
// 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=offto thewebEnrolmentUrl, 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 is unchanged.
Reading the result#
The same as in the mobile guide: Decision.Level (HIGH, MEDIUM, LOW), LivenessResult.Result (Live or Not Live) and FaceMatchResult.IsMatch. See 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.
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
CorrelationIdis stored per user, and the API key never reaches the browser - [ ] The
webEnrolmentUrlis embedded in an iframe withallow="camera; microphone"over HTTPS - [ ] The message handler checks
event.sourceandevent.origin, and handlesIDV_SESSION_COMPLETEandERROR(exact names) once, including when the person finishes on their phone (the iframe stays open until then) - [ ] On
IDV_SESSION_COMPLETEthe server (not the browser) callsdocument/dataanddocument/resultonce withx-api-keyandx-correlation-id - [ ]
HIGH,MEDIUMandLOWlead to approved, review and rejected, andERRORrestarts the flow - [ ] A verification belongs to one user: another user's id returns 404
- [ ] Verified in a browser with a
test_key