ScreenlyyIDDocs
Docs › Guides

Add identity verification to your web app

View as Markdown
Note

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. 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, 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 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_KEY on 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: idv in GlobalScreening, 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.
Shell
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)#

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
  }
});
EventMeaningWhat to do
IDV_SESSION_COMPLETEThe 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 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.

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#

StatusWhenBody
400instance/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"}
401Missing or invalid x-api-keyProblem-details JSON
500Result 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