Skip to Content
GuidesEnroll a face

Enroll a face

Capture one face image and submit it to the Slade ID backend as an enrollment for a specific subject.

Prerequisites

  • An initialised SladeID instance.
  • A <video> element in the DOM.
  • An enrolleeId — your system’s identifier for the subject.

Steps

  1. Create a FaceCaptureSession against the video element.
  2. Listen for 'captured'.
  3. In the listener, call sdk.enrollFace(enrolleeId, result).
  4. Call session.start().

Full example

import { SladeID, type FaceCaptureResult } from '@sladeid/slade-id-sdk';
 
const sdk = new SladeID({
  middlewareUrl: 'https://id.example.com',
  clientSecret: '<ClientSecret>',
});
 
const video = document.querySelector<HTMLVideoElement>('#camera')!;
 
async function enroll(enrolleeId: string): Promise<void> {
  const session = sdk.createFaceSession(video, {
    requireLiveness: true,
    antispoofThreshold: 0.7,
    holdSteadyMs: 3000,
  });
 
  return new Promise((resolve, reject) => {
    session.on('captured', async ({ result }: { result: FaceCaptureResult }) => {
      try {
        const enrolled = await sdk.enrollFace(enrolleeId, result);
        console.log('enrolled id:', enrolled.id);
        resolve();
      } catch (err) {
        reject(err);
      }
    });
 
    session.on('error', reject);
    session.start().catch(reject);
  });
}
 
await enroll('subject-123');

Response shape:

{
  "id": "f3c4b2a8-...",
  "enrollee": "subject-123",
  "createdAt": "2026-05-14T10:00:00Z",
  "raw": { "...": "untouched backend payload" }
}

What can go wrong

  • CaptureError with code CAMERA_PERMISSION_DENIED — the user blocked the camera prompt. Surface a “permission needed” UI and link them to browser settings. See Handle camera permission denial.
  • QualityError with code FACE_QUALITY_FAILED — couldn’t get a sharp, well-lit frame within maxFaceQualityRetries attempts. Ask the user to move closer to a light source or face the camera squarely.
  • QualityError with code ANTISPOOF_FAILED — real-confidence stayed below threshold. Confirm the user is presenting a live face, not a photo.
  • NetworkError with code REQUEST_TIMEOUT — the backend took longer than timeoutMs (default 15 seconds). Retry; consider bumping timeoutMs if your network conditions justify it.
  • AuthError with code UNAUTHORIZED — the ClientSecret is expired or rejected. Issue a fresh one.

See also

Capture a fingerprintHandle camera permission