Vouch SDK Identity Verification: Modal and File Upload

The identity module gives you two ways to verify that a real person controls the account they claim to own. The first method launches a hosted iframe modal that guides the user through capture — no custom UI required. The second method accepts files you have already collected, giving you full control over the capture experience. Both methods return the same result shape, so you can switch between them without changing downstream logic.

Method 1: `vouch.identity.verify(externalUserId)`

This method injects a hosted iframe modal into the current browser page. The modal walks the user through document capture and selfie liveness steps, then resolves the returned Promise once verification is complete. It is the recommended approach for browser-based applications because it requires no additional UI work on your side.

string

required

Your platform’s unique identifier for the user being verified. Vouch stores the result against this ID so you can retrieve it later.

import Vouch from 'vouch-sdk';

const vouch = new Vouch('your-api-key');

async function verifyUser(userId: string) {
  try {
    const result = await vouch.identity.verify(userId);

    if (result.data.identityVerified) {
      console.log('Identity confirmed ✓', result.data.id);
    } else {
      console.warn('Verification failed:', result.message);
    }
  } catch (err) {
    console.error('Verification error:', err);
  }
}

vouch.identity.verify() is a browser-only method. Calling it in a Node.js or server-side environment will throw because there is no DOM to inject the modal into.

Method 2: `vouch.identity.submitVerification(documentFile, selfieFrames, externalUserId)`

This method uploads a document image and an array of selfie frames directly to the Vouch API. Use it when your application already has its own camera or file-capture UI and you want to handle the user experience yourself.

File | Blob

required

A JPEG or PNG image of the user’s identity document. Maximum file size is 5 MB.

(File | Blob)[]

required

An array of JPEG or PNG selfie frames captured from the user’s camera. Provide between 3 and 15 frames for the best liveness detection accuracy.

string

required

Your platform’s unique identifier for the user. Same semantics as verify().

Provide 3–15 selfie frames for reliable liveness results. A single frame is accepted but significantly reduces detection confidence. Each individual file must be JPEG or PNG and must not exceed 5 MB.

import Vouch from 'vouch-sdk';

const vouch = new Vouch('your-api-key');

async function handleVerificationSubmit(
  docInput: HTMLInputElement,
  selfieInput: HTMLInputElement,
  userId: string
) {
  const documentFile = docInput.files?.[0];
  const selfieFiles = Array.from(selfieInput.files ?? []);

  if (!documentFile || selfieFiles.length === 0) {
    throw new Error('Document and at least one selfie frame are required.');
  }

  const result = await vouch.identity.submitVerification(
    documentFile,
    selfieFiles,
    userId
  );

  if (result.data.identityVerified) {
    console.log('Match score:', result.data.identityMatchScore);
    console.log('Document type:', result.data.documentType);
  } else {
    console.warn('Verification failed:', result.message);
  }
}

Only JPEG and PNG files are accepted. Submitting a PDF, HEIC, or other format will cause the request to fail. Convert files on the client before calling submitVerification.

Response fields

Both methods resolve with an IdentityVerifyResult object.

string

Top-level outcome of the verification request. Either "success" or "failed".

string

A human-readable description of the outcome, useful for logging or displaying error details to your support team.

object

The structured verification payload.

Show data fields

string

The Vouch-assigned unique identifier for this verification record.

string

The user ID you passed in, echoed back for correlation.

boolean

true if the document and selfie matched successfully and liveness passed. Use this as your primary decision field.

number | null

A numeric score from 0 to 99 representing how closely the selfie matches the document photo. A higher score means a stronger match. Returns null when the comparison could not be completed.

boolean

true if the anti-spoofing liveness check determined a real person was present during capture.

string | null

The detected document category. One of "passport", "drivers_license", or "national_id". Returns null if the document type could not be determined.

Gate sensitive user actions on both identityVerified: true and livenessPassed: true. A high match score alone does not confirm that a live person — rather than a photograph — was presented.

Get Started

Core Concepts

SDK Reference

Guides

Resources

Vouch SDK Identity Verification: Modal and File Upload

Method 1: `vouch.identity.verify(externalUserId)`

Method 2: `vouch.identity.submitVerification(documentFile, selfieFrames, externalUserId)`

Response fields

​Method 1: vouch.identity.verify(externalUserId)

​Method 2: vouch.identity.submitVerification(documentFile, selfieFrames, externalUserId)

​Response fields

Method 1: `vouch.identity.verify(externalUserId)`

Method 2: `vouch.identity.submitVerification(documentFile, selfieFrames, externalUserId)`

Response fields