# Express (Node.js)

> Add ScreenlyyID identity verification to an Express back end: create a session, then read the result after the hosted page reports it is done.

Canonical URL: https://www.screenlyyid.com/docs/recipes/express/

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`](https://www.screenlyyid.com/docs/authentication/create-instance/) 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`](https://www.screenlyyid.com/docs/api-reference/hosted-sdk-data/get-decision-result/). |

## Install
```bash
npm install express
```

Create a test key (see [Get a test key](https://www.screenlyyid.com/docs/ai-quickstart/#get-a-test-key)) and put it in your environment:

```bash
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
```bash
node server.js
```

```bash
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](https://www.screenlyyid.com/docs/integrations/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](https://www.screenlyyid.com/docs/integrations/web-app/) and the [Next.js recipe](https://www.screenlyyid.com/docs/recipes/nextjs/) for a complete page.

**Run it from the repo:** this is the code in [`express/`](https://github.com/ScreenlyyID/examples/tree/main/express) of the public examples repo ([ScreenlyyID/examples](https://github.com/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](https://www.screenlyyid.com/docs/ai-quickstart/) for the full API flow and the [error table](https://www.screenlyyid.com/docs/ai-quickstart/#errors).
