Verify
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
| Option | Type | Default | Description |
|---|---|---|---|
clientKey | string | Required | Public client key from the VOLTOM dashboard. |
prepare | boolean | true | Prepares the SDK at construction. Set false to prepare on demand. Camera access starts when an operation runs. |
apiUrl | string | https://api.voltom.io | API base URL. Accepts absolute HTTP or HTTPS URLs, including a base path. Set from your environment for local development. |
sdkUrl | string | https://sdk.voltom.io | Base 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. |
language | Language | Browser language, then en | UI 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 system | Overrides host .light, .dark, or data-theme selectors and system preference. |
debug | boolean | false | Collects capture diagnostics for state and the debug panel. An operation can override this value. |
video | HTMLVideoElement | Created for built-in UI | Required when UI is disabled. Supplies the capture video for a custom interface. |
ui | boolean | true | Opens a fullscreen overlay for each operation. Set false and provide video for a custom interface. |
authorize | ({ action: string }) => Promise<AuthorizedVerifyIntent> | None | Calls your server to create an intent. When omitted, requests use the public client key without an intent token. |
requireEyeLevelCamera | boolean | true | Requires camera alignment before accepting a face capture. |
capabilities | VerificationCapability[] | All five operations | Enables acquireFace, acquireDocument, acquireReference, matchID, and matchReference. Limits model preparation; disabled operations throw SDK_CAPABILITY_NOT_CONFIGURED. |
ocrEngine | OcrEngine | auto | Selects auto, tiny, small, japanese, chinese-simplified, chinese-traditional, cyrillic, or arabic OCR. |
faceDetector | 'high' | 'standard' | 'low' | standard | Selects the face detector model. |
threshold | number | 0.51 | Face match threshold for capture checks and server verification. |
poses | Pose[] | 'all' | faceStraight, faceUp, faceLeft, faceRight | Requires these four poses, no duplicates, and faceStraight first. Additional poses: faceDown, faceSmile, faceWinkLeft, faceTiltLeft, faceTiltRight. Remaining poses are ordered by difficulty unless randomized. |
randomizeFaceSequence | boolean | false | Randomizes pose order after faceStraight. |
requiredFaceStableFrames | number | 2 | Consecutive valid face frames required for capture. |
requiredDocumentStableFrames | number | 2 | Consecutive valid document frames required for capture. |
maxPitch | number | 8 | Face pose angle limit in degrees. Applies to capture guidance and server verification. |
minPitch | number | -20 | Face pose angle limit in degrees. Applies to capture guidance and server verification. |
maxYaw | number | 12 | Face pose angle limit in degrees. Applies to capture guidance and server verification. |
minYaw | number | -12 | Face pose angle limit in degrees. Applies to capture guidance and server verification. |
maxRoll | number | 8 | Face pose angle limit in degrees. Applies to capture guidance and server verification. |
minDocumentFaceAreaRatio | number | 0.02 | Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum. |
maxDocumentFaceAreaRatio | number | 0.3 | Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum. |
minDocumentFaceWidthRatio | number | 0.075 | Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum. |
maxDocumentFaceWidthRatio | number | 0.4 | Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum. |
minDocumentFaceHeightRatio | number | 0.1 | Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum. |
maxDocumentFaceHeightRatio | number | 0.65 | Document face geometry limit from 0 to 1. Each minimum must not exceed its matching maximum. |
minDocumentBoxRatio | number | 0.33 | Minimum document box ratio, from 0 to 1. |
maxDocumentTextAngleDifference | number | 16 | Maximum document text angle difference, from 0 to 90 degrees. |
showFaceOverlay | boolean | false | Draws the face detector overlay. Separate from capture guidance. |
showDocumentOverlay | boolean | false | Draws document and document face overlays. Separate from capture guidance. |
showTextOverlay | boolean | false | Draws OCR text when showDocumentOverlay is true. |
faceOverlayColor | string | transparent | Face overlay fill color. |
faceMeshColor | string | #38efb0 | Face mesh line color. |
documentOverlayColor | string | transparent | Document overlay fill color. |
documentBoxColor | string | #22d3ee | Document box line color. |
documentFaceBoxColor | string | #22d3ee | Document face box line color. |
documentFaceMeshColor | string | #38efb0 | Document face mesh line color. |
textColor | string | #22d3ee | OCR 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.
| Option | Type | Default | Description |
|---|---|---|---|
debug | boolean | Instance value | Collects capture diagnostics for state and the debug panel. An operation can override this value. |
poses | Pose[] | 'all' | Instance value | Requires these four poses, no duplicates, and faceStraight first. Additional poses: faceDown, faceSmile, faceWinkLeft, faceTiltLeft, faceTiltRight. Remaining poses are ordered by difficulty unless randomized. |
randomizeFaceSequence | boolean | Instance value | Randomizes pose order after faceStraight. |
showFaceOverlay | boolean | Instance value | Draws the face detector overlay. Separate from capture guidance. |
showDocumentOverlay | boolean | Instance value | Draws document and document face overlays. Separate from capture guidance. |
showTextOverlay | boolean | Instance value | Draws OCR text when showDocumentOverlay is true. |
Methods Reference
| Method | Result |
|---|---|
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.
| Event | When it fires | Event data |
|---|---|---|
voltom:in-progress | A verification operation starts. | None |
voltom:ready | A verification operation finishes, including after an error. | None |
voltom:camera-change | Camera activity changes. | { active: boolean } |
voltom:captures-change | Captured 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.
| Method | Path | Key | Purpose |
|---|---|---|---|
POST | /verify | Secret key | Create a verification intent. |
GET | /verify/op/{resultId} | Public or secret key | Read 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' | nullLimits 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.