ScreenlyyIDDocs
Docs › Recipes

Express (Node.js)

View as Markdown

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.

RouteWhat it does
POST /api/verificationsStep 1: calls instance/create and returns { verificationId, webEnrolmentUrl }.
GET /api/verifications/:idStep 4: after the front end receives IDV_SESSION_COMPLETE, reads the result once with document/result.

Install#

Shell
npm install express

Create a test key (see Get a test key) and put it in your environment:

Shell
export SCREENLYYID_API_KEY=test_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

server.js#

Add "type": "module" to package.json.

JAVASCRIPT
// 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#

Shell
node server.js
Shell
curl -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 CorrelationId against 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.