Quickstart

Install

npm

npm install @spruceid/verify-sdk

yarn

yarn add @spruceid/verify-sdk

pnpm

pnpm add @spruceid/verify-sdk

Quickstart

1. Backend — create a session

Create a backend route that calls fetchSessionData() with your API key and returns the session data to your frontend. The API key must stay server-side.

// Example: Express.js route
import express from 'express';
import { fetchSessionData } from '@spruceid/verify-sdk';

const app = express();
app.use(express.json());

const API_KEY = process.env.VERIFY_API_KEY;

app.post('/api/sessions', async (req, res) => {
  try {
    const sessionData = await fetchSessionData(API_KEY);
    res.json(sessionData);
  } catch (error) {
    console.error('Session creation failed:', (error as Error).message);
    res.status(500).json({ error: 'Failed to create verification session' });
  }
});

2. Frontend — launch verification

Fetch the session data from your backend, initialize the session, and launch the verification UI. The SDK injects an iframe into a <div> you specify.

<button id="verify-btn">Verify Identity</button>
<div id="verification-container"></div>

import {
  initVerificationSession,
  NAMESPACES_MDL_ALL_MANDATORY,
} from '@spruceid/verify-sdk';

document.getElementById('verify-btn').addEventListener('click', async () => {
  // Fetch session data from your backend
  const res = await fetch('/api/sessions', { method: 'POST' });
  const sessionData = await res.json();

  // Initialize the session
  const session = await initVerificationSession(sessionData);

  try {
    // Launch the verification iframe (resolves when the user completes)
    await session.launchMdlVerification(
      'verification-container',
      NAMESPACES_MDL_ALL_MANDATORY
    );

    // Verification succeeded — fetch results from your backend
    const resultsRes = await fetch('/api/sessions/results', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ id: sessionData.id }),
    });
    const results = await resultsRes.json();
    console.log('Verified:', results);

  } catch (error) {
    if ((error as Error).message === 'Verification cancelled by user') {
      console.log('User closed the verification modal');
    } else {
      console.error('Verification failed:', (error as Error).message);
    }
  }
});

3. Backend — fetch results

Create a second backend route that calls fetchSessionResults() to retrieve the verified identity data. Sessions are single-read — the data is removed after you fetch it.

import { fetchSessionResults } from '@spruceid/verify-sdk';

app.post('/api/sessions/results', async (req, res) => {
  const { id } = req.body;
  try {
    const results = await fetchSessionResults(id, API_KEY);

    if (results.status === 'success') {
      // Verified fields, keyed by ISO 18013-5 namespace
      const mdl = results.response['org.iso.18013.5.1'];
      res.json({
        status: 'success',
        givenName: mdl.given_name,
        familyName: mdl.family_name,
        birthDate: mdl.birth_date,
      });
    } else {
      res.json({
        status: 'error',
        errors: results.errors,
        warnings: results.warnings,
      });
    }
  } catch (error) {
    console.error('Failed to fetch results:', (error as Error).message);
    res.status(500).json({ error: 'Failed to fetch verification results' });
  }
});

For details on the response format, data types, and error handling, see Understanding results. For a complete working example, see the live demo. For full function signatures and types, see the SDK API Reference.

---

Error handling

For details on error messages and how to handle failures at each step of the verification flow, see Troubleshooting.