Web JavaScript - Verilock

Overview

The Web SDK ships two modules:

Module	File	Purpose
VerilockIdentity	`verilock-identity.js`	Drop-in modal widget for end-user verification
VerilockApi	`verilock-api.js`	Server-side API client for full API access

VerilockIdentity is designed for frontend use with a session token. VerilockApi requires an API key and must only be used from a backend server or secure environment.

Installation

Script tag

<!-- Modal widget (frontend) -->
<script src="https://cdn.verilock.io/js/verilock-identity.js"></script>

<!-- API client (backend / Node.js) -->
<script src="https://cdn.verilock.io/js/verilock-api.js"></script>

ES module

import { VerilockIdentity } from './verilock-identity.js';
import { VerilockApi } from './verilock-api.js';

npm

npm install @verilock/web-sdk

const { VerilockIdentity } = require('@verilock/web-sdk/identity');
const { VerilockApi } = require('@verilock/web-sdk/api');

VerilockIdentity renders a full-screen modal that walks the user through document capture, selfie, and verification — all inside the browser.

Quick start

const qi = new VerilockIdentity({
  sessionToken: 'tok_abc123',
  onComplete: (result) => {
    console.log('Decision:', result.decision);  // 'approved' or 'declined'
    console.log('Risk score:', result.risk_score);
  },
  onError: (error) => {
    console.error('Verification failed:', error.message);
  },
});

qi.start();

Configuration

new VerilockIdentity({
  // Required
  sessionToken: 'tok_abc123',

  // Callbacks
  onComplete: (result) => { /* Verification finished */ },
  onError: (error) => { /* Something went wrong */ },
  onStep: (step) => { /* Step changed: 'welcome', 'doc_front', 'doc_back', 'selfie', 'processing', 'result' */ },

  // Theme customization
  theme: {
    primaryColor: '#6366f1',   // Brand color for buttons and accents
    logoUrl: 'https://example.com/logo.png',  // Shown on the welcome screen
    borderRadius: '12px',
  },

  // Text overrides
  text: {
    welcomeTitle: 'Identity Verification',
    welcomeSubtitle: 'We need to verify your identity. This is quick and secure.',
    welcomeButton: 'Get started',
    docFrontTitle: 'Front of your document',
    docFrontSubtitle: 'Take a photo or upload the front of your government-issued ID.',
    docBackTitle: 'Back of your document',
    docBackSubtitle: 'Take a photo or upload the back of your document.',
    selfieTitle: 'Take a selfie',
    selfieSubtitle: 'Position your face in the frame. Ensure good lighting.',
    processingTitle: 'Verifying your identity',
    processingSubtitle: 'This usually takes less than a minute.',
    successTitle: 'Verification Complete',
    successSubtitle: 'Your identity has been successfully verified.',
    failureTitle: 'Verification Unsuccessful',
    failureSubtitle: 'We were unable to verify your identity.',
  },

  // Optional
  baseUrl: 'https://identity.verilock.io',  // Override API endpoint
});

Methods

Method	Description
`start()`	Open the verification modal and begin the flow
`destroy()`	Close the modal and release camera resources

Verification steps

The modal progresses through these steps automatically:

welcome — Greeting screen with instructions
doc_front — Capture front of ID (camera or file upload)
doc_back — Capture back of ID
selfie — Selfie capture with face oval guide
processing — Animated progress while the API verifies
result — Approved or declined screen

Each step supports both camera capture and file upload. If the browser does not support camera access, it falls back to file upload automatically.

Use the onStep callback to track user progress in your analytics or show custom UI alongside the modal.

The user can close the modal by clicking outside it or pressing the close button. You can also close it programmatically:

qi.destroy();

API Client

VerilockApi is a full-featured client for the Verilock REST API. It uses fetch() and works in modern browsers (for server-side rendering) and Node.js 18+.

Initialize

const api = new VerilockApi({
  apiKey: 'qi_live_...',
  baseUrl: 'https://verilock.io/api/v1',  // default
  timeout: 30000,   // request timeout in ms (default: 30s)
  maxRetries: 2,    // retries on 429/5xx (default: 2)
});

Sessions

// Create a verification session
const session = await api.sessions.create({
  applicant_email: 'john@example.com',
  external_id: 'user_12345',
  redirect_url: 'https://example.com/callback',
  metadata: { plan: 'premium' },
});

// List sessions
const list = await api.sessions.list({
  status: 'completed',
  decision: 'approved',
  per_page: 20,
});

// Retrieve a session
const detail = await api.sessions.retrieve('ses_abc123');

// Upload a document
await api.sessions.uploadDocument('ses_abc123', fileBlob, 'front', 'passport');

// Upload a selfie
await api.sessions.uploadSelfie('ses_abc123', selfieBlob);

// Submit for evaluation
await api.sessions.submit('ses_abc123');

AML Screening

// Screen a person
const aml = await api.aml.screen({
  name: 'John Doe',
  date_of_birth: '1990-01-15',
  nationality: 'US',
});

// Retrieve result
const amlResult = await api.aml.retrieve(aml.id);

// Submit decision
await api.aml.decide(aml.id, { decision: 'clear', notes: 'No matches found.' });

Transaction Screening

// Screen a transaction
const tx = await api.transactions.screen({
  transaction_ref: 'TX-001',
  sender_name: 'Alice Smith',
  sender_country: 'US',
  receiver_name: 'Bob Johnson',
  receiver_country: 'NG',
  amount: 5000,
  currency: 'USD',
  transaction_type: 'wire_transfer',
});

// Batch screening
const batch = await api.transactions.screenBatch({
  transactions: [
    { transaction_ref: 'TX-002', sender_name: 'Alice', receiver_name: 'Charlie', amount: 200, currency: 'EUR' },
    { transaction_ref: 'TX-003', sender_name: 'Alice', receiver_name: 'Diana', amount: 15000, currency: 'USD' },
  ],
});

// List with risk filter
const highRisk = await api.transactions.list({ risk_level: 'high', per_page: 50 });

// Get available transaction types
const types = await api.transactions.listTypes();

Wallet Screening

// Screen a crypto wallet
const wallet = await api.wallet.screen({
  address: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD08',
  network: 'ethereum',
});

const walletResult = await api.wallet.retrieve(wallet.id);

Credentials

// Create a reusable KYC credential
const cred = await api.credentials.create({
  session_id: 'ses_abc123',
  shared_fields: ['full_name', 'date_of_birth', 'document_number'],
  expires_in_days: 365,
});

// Verify a credential token
const verified = await api.credentials.verify({ token: 'cred_token_...' });

// Revoke
await api.credentials.revoke(cred.id);

Additional endpoints

// Biometric authentication
await api.biometric.authenticate('ses_abc123', selfieBlob, 0.85);
const bioResult = await api.biometric.retrieve('bio_abc123');

// Government database validation
const providers = await api.database.listProviders();
const dbResult = await api.database.validate({
  provider: 'ng_nin',
  first_name: 'John',
  last_name: 'Doe',
  document_number: '12345678901',
});

// Face search (1:N duplicate detection)
const faces = await api.faceSearch.search({ session_id: 'ses_abc123', threshold: 0.9 });

// Age verification
await api.ageVerify.verify(photoBlob, 18);

Integration Patterns

The default VerilockIdentity modal overlays your page. Best for single-page apps and checkout flows:

new VerilockIdentity({ sessionToken: token, onComplete }).start();

Iframe embed

Embed the hosted verification page in an iframe for a contained experience:

<iframe
  src="https://identity.verilock.io/verify/tok_abc123"
  width="480"
  height="700"
  allow="camera"
  style="border: none; border-radius: 12px;"
></iframe>

Listen for completion via postMessage:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://identity.verilock.io') return;
  if (event.data.type === 'verification_complete') {
    console.log('Decision:', event.data.decision);
  }
});

Redirect

Redirect the user to the hosted verification page. They return to your redirect_url when finished:

// Create session with redirect URL on your backend
const session = await api.sessions.create({
  applicant_email: 'john@example.com',
  redirect_url: 'https://example.com/verification-complete',
});

// Redirect the user
window.location.href = session.session_url;

The redirect URL receives ?session_id=ses_abc123&decision=approved as query parameters.

Error Handling

The API client throws VerilockError on failure:

try {
  await api.aml.screen({ name: 'John Doe' });
} catch (error) {
  if (error.name === 'VerilockError') {
    console.log(error.code);       // e.g. 'insufficient_credits'
    console.log(error.message);    // Human-readable description
    console.log(error.statusCode); // HTTP status code
    console.log(error.body);       // Full error response object
  }
}

The client automatically retries on 429 (rate limited) and 5xx (server error) responses with exponential backoff. You can configure this with the maxRetries option.

​Overview

​Installation

​Script tag

​ES module

​npm

​Modal Verification Widget

​Quick start

​Configuration

​Methods

​Verification steps

​Closing the modal

​API Client

​Initialize

​Sessions

​AML Screening

​Transaction Screening

​Wallet Screening

​Credentials

​Additional endpoints

​Integration Patterns

​Modal (recommended)

​Iframe embed

​Redirect

​Error Handling

Overview

Installation

Script tag

ES module

npm

Modal Verification Widget

Quick start

Configuration

Methods

Verification steps

Closing the modal

API Client

Initialize

Sessions

AML Screening

Transaction Screening

Wallet Screening

Credentials

Additional endpoints

Integration Patterns

Modal (recommended)

Iframe embed

Redirect

Error Handling