Express (Node.js)
An Express server with the two routes a ScreenlyyID integration needs. The API key and the CorrelationId stay on the server; your front end only receives a verificationId and the hosted page URL. Node 18 or later.
| Route | What it does |
|---|---|
POST /api/verifications | Step 1: calls instance/create and returns { verificationId, webEnrolmentUrl }. |
GET /api/verifications/:id | Step 4: after the front end receives IDV_SESSION_COMPLETE, reads the result once with document/result. |
Install#
npm install expressCreate a test key (see Get a test key) and put it in your environment:
export SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxserver.js#
Add "type": "module" to package.json.
// Express back end for ScreenlyyID identity verification. Node 18 or later.
// The API key and the CorrelationId stay on this server: the browser only gets a verificationId and the hosted page URL.
import express from "express";
import { randomUUID } from "node:crypto";
const API = "https://api.screenlyyid.com";
const apiKey = process.env.SCREENLYYID_API_KEY; // a test_ key while you build
if (!apiKey) throw new Error("SCREENLYYID_API_KEY is not set");
// verificationId -> { userId, correlationId }. In memory for the example; use your database.
const sessions = new Map();
const app = express();
app.use(express.json());
// Step 1: create a verification session (server side).
app.post("/api/verifications", async (req, res) => {
const userId = req.user?.id ?? "demo-user"; // replace with your own authentication
const r = await fetch(`${API}/api/v1/instance/create`, {
method: "POST",
headers: { "x-api-key": apiKey, "Content-Type": "application/json" },
body: JSON.stringify({ GlobalScreening: ["idv"], CustomerIntelligence: [] }),
});
if (!r.ok) return res.status(502).json({ error: `ScreenlyyID instance/create failed (HTTP ${r.status})` });
const { CorrelationId, webEnrolmentUrl } = await r.json(); // the property names are exactly these
const verificationId = randomUUID();
sessions.set(verificationId, { userId, correlationId: CorrelationId });
res.status(201).json({ verificationId, webEnrolmentUrl }); // the CorrelationId is not sent to the browser
});
// Step 4: after the browser reports IDV_SESSION_COMPLETE, read the result once.
app.get("/api/verifications/:id", async (req, res) => {
const session = sessions.get(req.params.id);
if (!session || session.userId !== (req.user?.id ?? "demo-user")) return res.status(404).json({ error: "Unknown verification" });
const r = await fetch(`${API}/api/v1/document/result`, {
headers: { "x-api-key": apiKey, "x-correlation-id": session.correlationId },
});
if (r.status === 200) return res.json({ status: "ready", result: await r.json() });
if (r.status === 500) return res.json({ status: "pending" }); // asked before the capture finished
res.status(502).json({ error: `ScreenlyyID document/result failed (HTTP ${r.status})` });
});
app.listen(process.env.PORT || 3000, () => console.log("listening"));Run and test#
node server.jscurl -s -X POST localhost:3000/api/verifications
# {"verificationId":"...","webEnrolmentUrl":"https://app.screenlyyid.com/idv/..."}
curl -s localhost:3000/api/verifications/VERIFICATION_ID
# {"status":"pending"} (asked before the person has finished the capture)Open webEnrolmentUrl in a browser or embed it as described in Web app. When the page reports IDV_SESSION_COMPLETE, the same GET returns {"status":"ready","result":{...}}.
The front end is the same as for any web app: embed webEnrolmentUrl in an iframe with allow="camera; microphone", listen for the event, then call your GET route. See Web app and the Next.js recipe for a complete page.
Run it from the repo: this is the code in express/ of the public examples repo (ScreenlyyID/examples), which has a README and an .env.example.
What this does not include#
- Your own sign-in. The sample uses a fixed
demo-user. Replace it with your authentication, and keep the check that a verification belongs to the person asking. - A database. Sessions are kept in memory so the sample stays short. Store the
CorrelationIdagainst your user in your database. - HTTPS and rate limits. Add both before this faces the internet.
See the AI quickstart for the full API flow and the error table.