API Reference

Complete reference for all VECU IDV Web SDK methods and their parameters.

createVecuIDVSDK()

Factory function to create an SDK instance.

import { createVecuIDVSDK } from 'vec-idp-web-sdk';

const sdk = createVecuIDVSDK({
  deploymentStage: 'sandbox',
  bearerToken: 'your-bearer-token',
  debug: true,
});

See Configuration for all available options.

startVerificationWithCustomer()

Start a verification flow with customer information. This is the primary method for initiating verification.

const cleanup = await sdk.startVerificationWithCustomer(
  containerSelector: string | HTMLElement,
  options: VerificationOptions
): Promise<() => void>

Parameters

VerificationOptions

interface VerificationOptions {
  customerInfo: CustomerInfo;
  referenceId: string;
  mode?: 'modal' | 'embedded';
  deploymentStage?: 'sandbox' | 'production';
  theme?: Record<string, unknown>;
  language?: string;
  config?: VerificationConfig;
  onProgress?: (event: ProgressEvent) => void;
  onSuccess?: (result: VerificationResult) => void;
  onError?: (error: Error) => void;
}

CustomerInfo

interface CustomerInfo {
  firstName: string; // Required
  lastName: string; // Required
  middleName?: string;
  email?: string;
  phone?: string;
  address?: {
    line1?: string;
    line2?: string;
    locality?: string; // City
    minorAdminDivision?: string; // County
    majorAdminDivision?: string; // State/Province
    country?: string;
    postalCode?: string;
    type?: 'residential' | 'commercial';
  };
}

Returns

Returns a Promise that resolves to a cleanup function. Call this function when verification is complete or when the user navigates away.

Example

const cleanup = await sdk.startVerificationWithCustomer(
  document.getElementById('verification-container'),
  {
    customerInfo: {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john.doe@example.com',
      phone: '+1-555-123-4567',
      address: {
        line1: '123 Main St',
        locality: 'Anytown',
        majorAdminDivision: 'CA',
        country: 'US',
        postalCode: '12345',
        type: 'residential',
      },
    },
    referenceId: `verification-${Date.now()}`,
    mode: 'embedded',
    onProgress: event => {
      console.log(`Progress: ${event.step} (${event.percentage}%)`);
    },
    onSuccess: result => {
      console.log('Verification completed!', result);
    },
    onError: error => {
      console.error('Verification failed:', error);
    },
    config: {
      qrCode: true,
    },
  }
);

// Cleanup when done
cleanup();

startReverification()

Re-verify a returning user's identity by reusing existing document data and capturing a fresh selfie.

const cleanup = await sdk.startReverification(
  containerSelector: string | HTMLElement,
  options: ReverificationOptions
): Promise<() => void>

Parameters

ReverificationOptions

interface ReverificationOptions {
  referenceId: string; // Required: Links to original verification
  phoneNumber?: string; // Phone number for SMS notifications
  sendMessage?: boolean; // Control SMS sending (default: true)
  mode?: 'modal' | 'embedded';
  deploymentStage?: 'sandbox' | 'production';
  config?: {
    qrCode?: boolean;
  };
  onProgress?: (event: ProgressEvent) => void;
  onSuccess?: (result: VerificationResult) => void;
  onError?: (error: Error) => void;
}

When to Use Reverification

• User has completed a full verification previously and you have their referenceId
• You need to re-verify the user's identity after a period of time
• Document data is still valid but selfie needs to be updated for security
• You want to reduce friction for returning users while maintaining security

Example

const cleanup = await sdk.startReverification('#verification-container', {
  referenceId: 'customer-12345',
  phoneNumber: '+1-555-123-4567',
  sendMessage: true,
  mode: 'embedded',
  config: {
    qrCode: true,
  },
  onProgress: event => {
    console.log(`Progress: ${event.step} (${event.percentage}%)`);
  },
  onSuccess: result => {
    console.log('Reverification completed!', result);
  },
  onError: error => {
    console.error('Reverification failed:', error);
  },
});

// Cleanup when done
cleanup();

updateConfig()

Update SDK configuration after initialization.

await sdk.updateConfig(config: Partial<SDKConfig>): Promise<void>

Parameters

Example

// Update configuration before starting verification
await sdk.updateConfig({
  deploymentStage: 'production',
  bearerToken: 'new-bearer-token',
  debug: false,
});

// Now safe to start verification
await sdk.startVerificationWithCustomer('#container', {
  /* ... */
});

Event Methods

on()

Subscribe to SDK events.

sdk.on(eventName: SdkEvent, handler: (event: any) => void): void

once()

Subscribe to an event once (automatically unsubscribes after first trigger).

sdk.once(eventName: SdkEvent, handler: (event: any) => void): void

off()

Unsubscribe from an event.

sdk.off(eventName: SdkEvent, handler: (event: any) => void): void

Example

const progressHandler = event => {
  console.log(`Step: ${event.step}, Progress: ${event.percentage}%`);
};

// Subscribe
sdk.on(SdkEvent.VERIFICATION_PROGRESS, progressHandler);

// Unsubscribe later
sdk.off(SdkEvent.VERIFICATION_PROGRESS, progressHandler);

// Subscribe once
sdk.once(SdkEvent.VERIFICATION_COMPLETED, event => {
  console.log('Verification completed:', event.data);
});

See Events for a complete list of available events.

destroy()

Destroy the SDK instance completely, releasing all resources.

sdk.destroy(): void

Example

// When done with the SDK entirely
sdk.destroy();

Global SDK (UMD Bundle)

When using the UMD bundle, the SDK is available as window.VecuIDVSDK:

configure()

Configure the global SDK instance.

window.VecuIDVSDK.configure({
  deploymentStage: 'sandbox',
  bearerToken: 'your-bearer-token',
  debug: true,
});

startVerificationWithCustomer()

Same as the factory function method.

const cleanup = await window.VecuIDVSDK.startVerificationWithCustomer(
  '#container',
  {
    /* options */
  }
);

startReverification()

Same as the factory function method.

const cleanup = await window.VecuIDVSDK.startReverification('#container', {
  /* options */
});

Error Handling

The SDK provides structured error codes in the onError callback:

Error Codes

Backend Validation Errors (v1.5.5+)

These errors are returned from backend validation when customer data fails provider validation. They include a recoverable: true flag, indicating the user can correct their data and retry.

Backend validation errors include additional metadata:

interface BackendValidationError {
  code: string; // e.g., 'INVALID_ZIP_CODE'
  message: string; // e.g., 'The zip code is invalid'
  category: 'validation_error';
  recoverable: true; // User can fix and retry
  timestamp: string; // ISO 8601 timestamp
}

Example Error Handling

const cleanup = await sdk.startVerificationWithCustomer('#container', {
  customerInfo: {
    /* ... */
  },
  onError: error => {
    switch (error.code) {
      case 'CONSENT_DECLINED':
        console.log('User declined consent');
        break;

      case 'USER_CANCELLED':
        console.log('User cancelled verification');
        break;

      case 'TOKEN_EXCHANGE_FAILED':
        window.location.href = '/login?session_expired=true';
        break;

      case 'VALIDATION_ERROR':
        const fieldErrors = error.details?.validationErrors || [];
        console.error('Validation failed:', fieldErrors);
        break;

      // Backend validation errors (v1.5.5+)
      case 'INVALID_ZIP_CODE':
      case 'INVALID_ADDRESS':
      case 'INVALID_STATE':
      case 'INVALID_CITY':
      case 'INVALID_COUNTRY':
      case 'INVALID_PHONE':
      case 'INVALID_EMAIL':
        // These are recoverable - prompt user to correct their data
        console.error(`Validation error: ${error.message}`);
        if (error.details?.recoverable) {
          // Show form to user to correct the specific field
          showCorrectionForm(error.code, error.message);
        }
        break;

      default:
        console.error('Verification error:', error);
    }
  },
});

Next Steps

• Events - Learn about SDK events
• Configuration - Configuration options reference
• Troubleshooting - Common issues and solutions