VOLTOM
VOLTOM
Почему VOLTOMРешенияЦеныВарианты использованияДокументацияКонтакты
Войти
Начать
VOLTOMНастоящие люди. Более безопасный интернет.
О компанииКонтактыУсловияКонфиденциальность
← All documentation

Verify

VOLTOM Verify

  • Quick start
  • Configuration
  • Instance options
  • Methods
  • Flows
    • Acquire a face
    • Acquire a document
    • Match an identity document
    • Match a reference
  • Results
  • Events
  • REST API
  • Limits and support
  • Pricing explained
  • Explore FaceGate
  • Explore FaceKey

Quick Start

Generate your API keys in the VOLTOM dashboard and use clientKey to initialize the SDK. Create VoltomVerify without a root element. Operations open a fullscreen overlay. Face and document checks run on the server. Reference preparation runs locally. Camera access starts only after a user action.

Run the full example in the browser: Open the Verify playground.

<html lang="en">
  <head>
    <script src="https://sdk.voltom.io/v1/verify.dist.js"></script>
  </head>
  <body>
    <button id="start" type="button">Start verification</button>
    <script type="module">
      const verify = new window.VoltomVerify({
        clientKey: 'YOUR_CLIENT_KEY',
        authorize: ({ action }) =>
          fetch('/api/verify/intent', {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({ action }),
          }).then((response) => response.json()),
      });

      await verify.prepare();

      document.querySelector('#start').addEventListener('click', async () => {
        const result = await verify.matchID();

        if (result.outcome === 'pass') {
          await fetch('/api/verify/complete', {
            method: 'POST',
            headers: { 'content-type': 'application/json' },
            body: JSON.stringify({ resultId: result.resultId }),
          });
        }
      });
    </script>
  </body>
</html>

Configuration Reference

OptionTypeDefaultDescription
clientKeystringRequiredPublic client key from the VOLTOM dashboard.
preparebooleantruePrepares the SDK at construction. Set false to prepare on demand. Camera access starts when an operation runs.
apiUrlstringhttps://api.voltom.ioAPI base URL. Accepts absolute HTTP or HTTPS URLs, including a base path. Set from your environment for local development.
sdkUrlstringhttps://sdk.voltom.ioBase URL for models, WASM, locales, and other assets. Uses the same URL rules as apiUrl. All instances in a loaded SDK runtime must use the same sdkUrl; a conflicting URL throws INVALID_OPTIONS. Script and import usage have identical defaults.
languageLanguageBrowser language, then enUI and, in Verify, OCR language. Supports ar, ch, de, en, es, fr, it, ja, pt, ru, zh. Chinese locales zh-TW, zh-HK, and zh-MO select ch.
theme'light' | 'dark'Host theme, then systemOverrides host .light, .dark, or data-theme selectors and system preference.
debugbooleanfalseCollects capture diagnostics for state and the debug panel. An operation can override this value.
videoHTMLVideoElementCreated for built-in UIRequired when UI is disabled. Supplies the capture video for a custom interface.
uibooleantrueOpens a fullscreen overlay for each operation. Set false and provide video for a custom interface.
authorize({ action: string }) => Promise<AuthorizedVerifyIntent>NoneCalls your server to create an intent. When omitted, requests use the public client key without an intent token.
requireEyeLevelCamerabooleantrueRequires camera alignment before accepting a face capture.
capabilitiesVerificationCapability[]All five operationsEnables acquireFace, acquireDocument, acquireReference, matchID, and matchReference. Limits model preparation; disabled operations throw SDK_CAPABILITY_NOT_CONFIGURED.
ocrEngineOcrEngineautoSelects auto, tiny, small, japanese, chinese-simplified, chinese-traditional, cyrillic, or arabic OCR.
faceDetector'high' | 'standard' | 'low'standardSelects the face detector model.
thresholdnumber0.51Face match threshold for capture checks and server verification.
posesPose[] | 'all'faceStraight, faceUp, faceLeft, faceRightRequires these four poses, no duplicates, and faceStraight first. Additional poses: faceDown, faceSmile, faceWinkLeft, faceTiltLeft, faceTiltRight. Remaining poses are ordered by difficulty unless randomized.
randomizeFaceSequencebooleanfalseRandomizes pose order after faceStraight.
requiredFaceStableFramesnumber2Consecutive valid face frames required for capture.
requiredDocumentStableFramesnumber2Consecutive valid document frames required for capture.
maxPitchnumber8Face pose angle limit in degrees. Applies to capture guidance and server verification.
minPitchnumber-20Face pose angle limit in degrees. Applies to capture guidance and server verification.
maxYawnumber12Face pose angle limit in degrees. Applies to capture guidance and server verification.
minYawnumber-12Face pose angle limit in degrees. Applies to capture guidance and server verification.
maxRollnumber8Face pose angle limit in degrees. Applies to capture guidance and server verification.
minDocumentFaceAreaRationumber0.02Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum.
maxDocumentFaceAreaRationumber0.3Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum.
minDocumentFaceWidthRationumber0.075Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum.
maxDocumentFaceWidthRationumber0.4Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum.
minDocumentFaceHeightRationumber0.1Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum.
maxDocumentFaceHeightRationumber0.65Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum.
minDocumentBoxRationumber0.33Minimum document box ratio, from 0 to 1.
maxDocumentTextAngleDifferencenumber16Maximum document text angle difference, from 0 to 90 degrees.
showFaceOverlaybooleanfalseDraws the face detector overlay. Separate from capture guidance.
showDocumentOverlaybooleanfalseDraws document and document face overlays. Separate from capture guidance.
showTextOverlaybooleanfalseDraws OCR text when showDocumentOverlay is true.
faceOverlayColorstringtransparentFace overlay fill color.
faceMeshColorstring#38efb0Face mesh line color.
documentOverlayColorstringtransparentDocument overlay fill color.
documentBoxColorstring#22d3eeDocument box line color.
documentFaceBoxColorstring#22d3eeDocument face box line color.
documentFaceMeshColorstring#38efb0Document face mesh line color.
textColorstring#22d3eeOCR overlay text color.

Omitted options and explicit undefined use defaults. Explicit false is preserved. For local development, pass apiUrl and sdkUrl from your environment.

Instance Options Reference

Use configure(options) to update instance options. Each flow reads a snapshot at startup. Changes during a flow apply to its next run, including retry. Use stop() to cancel. Omitted options and undefined retain current values.

OptionTypeDefaultDescription
debugbooleanInstance valueCollects capture diagnostics for state and the debug panel. An operation can override this value.
posesPose[] | 'all'Instance valueRequires these four poses, no duplicates, and faceStraight first. Additional poses: faceDown, faceSmile, faceWinkLeft, faceTiltLeft, faceTiltRight. Remaining poses are ordered by difficulty unless randomized.
randomizeFaceSequencebooleanInstance valueRandomizes pose order after faceStraight.
showFaceOverlaybooleanInstance valueDraws the face detector overlay. Separate from capture guidance.
showDocumentOverlaybooleanInstance valueDraws document and document face overlays. Separate from capture guidance.
showTextOverlaybooleanInstance valueDraws OCR text when showDocumentOverlay is true.

Methods Reference

MethodResult
preload()Loads the language and models before a verification flow.
prepare()Calls preload(), validates the client key, initializes models, and prepares the capture interface.
configure(options)Updates instance poses, randomization, overlays, and debug for subsequent flows.
acquireReference(file)Prepares and stores the selected portrait and its yaw, pitch, and roll locally. Returns a VoltomReference. Does not open the camera or call the server.
forgetReference()Clears the current reference and its preview while retaining face captures. Returns void.
acquireFace()Captures and verifies a live face. Uses faceStraight and the acquired reference orientation when a reference exists; otherwise uses configured poses.
acquireDocument()Starts a document flow after a user action.
matchID()Acquires missing face and document inputs, then compares them. Reuses successful acquisitions.
matchReference(file)Prepares an image or PDF reference, acquires a face if missing, and compares them. Accepts a Blob.
forgetFace()Clears captured face images, face matching state, and the stored face verification identifier. Clears match feedback and emits voltom:captures-change. Returns void.
forgetDocument()Clears document captures, identity, document codes, document analysis, and the stored document verification identifier. Clears match feedback and emits voltom:captures-change. Returns void.
stop()Stops camera use and clears the active flow.
caniuse()Returns browser support and unsupported features.
dispose()Permanently disposes the client: stops active work, releases the camera, removes subscriptions, and clears collected data. Do not reuse it; create a new client. Shared model caches remain loaded.

Flows

Use explicit acquisition steps for a stepper or call a matching method to acquire missing inputs automatically. Server verification calls authorize to create the intent on your server, consumes it in the browser, and returns a VoltomVerificationResult. Resolve the outcome on your server with the resultId.

Acquire a face

Capture a live face and check liveness after a user action.

document.querySelector('#start').addEventListener('click', async () => {
  const result = await verify.acquireFace();
  console.log(result.matched);
});

Acquire a document

Capture an identity document and read its extracted identity when available.

document.querySelector('#start').addEventListener('click', async () => {
  const result = await verify.acquireDocument();
  console.log(result.identity);
});

Match an identity document

Capture a live face and document, then compare them. The server runs the required checks in sequence.

document.querySelector('#start').addEventListener('click', async () => {
  const result = await verify.matchID();
  console.log(result.matched);
});

Match a reference

Compare a live face with the first detected face in an image or the first page of a PDF. Existing face captures are reused even when acquired with default poses.

document.querySelector('#start').addEventListener('click', async () => {
  const result = await verify.matchReference(file);
  console.log(result.matched);
});

Separate acquisition steps

Acquisition results are stored on the instance. Explicit acquisition starts a new capture. Matching reuses successful captures. A changed reference replaces the stored portrait without clearing face captures. Reference pose matching uses yaw, pitch, and roll within the shared 15 degree tolerance.

verify.configure({ debug: true });
await verify.acquireReference(file);
await verify.acquireFace();
const result = await verify.matchReference(file);

verify.forgetReference();
await verify.acquireFace();
await verify.acquireDocument();
const identity = await verify.matchID();

Results

Technical failures and cancellation reject the operation with a VoltomSdkError. Completed verification and match rejections return a result. Use error.code for decisions. error.message contains stable English text; the SDK UI translates messages separately. HTTP errors include status. Errors for completed results include resultId when available.

import { Errors, isSdkError } from '@voltom.io/sdk/verify';

try {
  const result = await verify.matchID();
  console.log(result);
} catch (error) {
  if (!isSdkError(error)) throw error;
  if (error.code !== Errors.OPERATION_CANCELLED) {
    console.error(error.code, error.message, error.status, error.resultId);
  }
}

Script integrations use VoltomVerify.Errors and VoltomVerify.isSdkError. Shared codes include OPERATION_CANCELLED, OPERATION_TIMEOUT, OPERATION_IN_PROGRESS, SDK_DISPOSED, INTENT_TOKEN_INVALID, NETWORK_ERROR, and INVALID_SERVICE_RESPONSE. Cancellation and network errors do not confirm whether a server operation completed. Resolve the result on your server before you retry a protected action.

All Verify methods return this result.

type VoltomVerificationResult = {
  resultId: string;
  action: 'verify_face' | 'verify_document' | 'match_id' | 'match_reference';
  outcome: 'pass' | 'fail';
  matched: boolean;
  score: number | null;
  threshold: number | null;
  reason: ErrorCode | null;
  documentCode: string | null;
  identity: VoltomIdentity | null;
  completedAt: string | null;
  createdAt: string;
};

type VoltomIdentity = {
  document: {
    source: 'MRZ' | 'AAMVA' | 'OCR';
    type: 'PASSPORT' | 'ID' | 'VISA' | 'DRV' | 'PERMIT' | null;
    issuing_country: string | null;
    number: string | null;
    issuing_authority: string | null;
    issue_date: string | null;
    expiry_date: string | null;
    optional_data: string | null;
  };
  holder: {
    first_name: string | null;
    last_name: string | null;
    middle_name: string | null;
    birth_place: string | null;
    birth_date: string | null;
    sex: 'M' | 'F' | 'X' | null;
    nationality: string | null;
    personal_number: string | null;
  };
  address: {
    full: string | null;
    street: string | null;
    city: string | null;
    state_province: string | null;
    postal_code: string | null;
  } | null;
};

Check outcome and matched together. outcome: 'pass' means the verification passed. A result can have matched: false. reason and identity contain normalized document details when available. SDK results omit raw MRZ and AAMVA data.

Resolve the outcome

Use the resultId returned by the SDK to resolve the outcome from VOLTOM with GET /verify/op/{resultId}. Send the secret key in the Authorization header from your server. Never expose the secret key in a browser.

const response = await fetch(
  `https://api.voltom.io/verify/op/${encodeURIComponent(resultId)}`,
  {
    headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}` },
    cache: 'no-store',
  },
);

if (!response.ok) throw new Error('Could not resolve the verification outcome');

const outcome = await response.json();

if (outcome.status === 'resolved' && outcome.outcome === 'pass') {
  grantAccess();
}

Check status and outcome together. A resolved verification can still have outcome: 'fail'. The endpoint returns the intent outcome.

Events

Listen for these events on verify.events.

EventWhen it firesEvent data
voltom:in-progressA verification operation starts.None
voltom:readyA verification operation finishes, including after an error.None
voltom:camera-changeCamera activity changes.{ active: boolean }
voltom:captures-changeCaptured data changes.VoltomCaptureResult

Useful event fields include identity, captures, documentCodes, and optional document. Entries in captures are Blob images keyed by pose or document side, for example captures.faceStraight, captures.documentFront, or captures.documentBack.

verify.events.addEventListener('voltom:in-progress', () => {});
verify.events.addEventListener('voltom:ready', () => {});

verify.events.addEventListener('voltom:camera-change', (event) => {
  console.log(event.detail.active);
});

verify.events.addEventListener('voltom:captures-change', (event) => {
  const faceCapture = event.detail.captures.faceStraight;
  console.log(faceCapture); // Blob | undefined
});

REST API

Create the intent on your server with the secret key, consume it in the browser with the SDK, then resolve the outcome on your server with the secret key.

MethodPathKeyPurpose
POST/verifySecret keyCreate a verification intent.
GET/verify/op/{resultId}Public or secret keyRead the verification outcome.

Create an intent

// Your server creates the intent with the secret key.
app.post('/api/verify/intent', async (request, response) => {
  const upstream = await fetch('https://api.voltom.io/verify', {
    method: 'POST',
    headers: {
      authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify(request.body),
  });

  const intent = await upstream.json();

  response.status(upstream.status).json(intent);
});

Resolve the outcome

// Your server resolves the outcome with the secret key.
const upstream = await fetch(`https://api.voltom.io/verify/op/${encodeURIComponent(resultId)}`, {
  headers: { authorization: `Bearer ${process.env.VOLTOM_SECRET_KEY}` },
  cache: 'no-store',
});

const outcome = await upstream.json();
// outcome.status: 'pending' | 'consumed' | 'resolved' | 'expired' | 'failed'
// outcome.outcome: 'pass' | 'fail' | 'error' | null

Limits and Support

Each UTC calendar month includes 100 Verify checks. Unused free checks expire monthly. Extra Verify checks cost $0.05.

For support, write to us through Contact Us. Custom integration work is separately quoted.

Pricing Explained

Verify costs $0.05 per verification. Each UTC calendar month includes 100 free Verify checks. Unused free checks do not roll over.

A method that submits more than one verification is billed for each submitted verification. matchID submits up to three verifications; matchReference submits up to two. Successful acquisitions are reused. Local reference preparation is not billed.