API Field Reference

Comprehensive guide to SDK field semantics, constraints, validation rules, and default values. Understanding these details ensures successful integration and prevents common configuration errors.

SDK Documentation Quick Start Guide

Purpose of This Guide

This reference explains the semantic meaning, validation constraints, and behavioral consequences of each field in the SDK API. Understanding these details helps you:

Choose the correct field values for your use case (especially referenceId)
Avoid validation errors and failed verification attempts
Enable advanced features like reverification and session resumption
Properly correlate webhook events with your customer records

referenceId (Critical)

Definition

A client-controlled identifier that represents YOUR logical entity for this verification session. This is your primary key for tracking verifications across multiple workflows.

Type & Format

Type: string
Format: No specific format requirements - any valid string
Recommended Max Length: 255 characters

Required vs Optional

Method	Required?	Default if not provided
`startVerificationWithCustomer()`	Optional	`customer_${Date.now()}`
`startReverification()`	REQUIRED	N/A - must provide

The Auto-Generation Problem

When referenceId is not provided to startVerificationWithCustomer():

SDK automatically generates customer_1704451234567 (timestamp-based)
Each verification attempt gets a DIFFERENT ID
Reverification will FAIL - cannot link to original verification
Cannot resume incomplete verifications
Webhook events cannot be correlated by customer

Semantic Meaning

The referenceId serves multiple purposes:

1. Identity Tracking

Links all verification attempts for a single real-world person

2. Session Resumability

Enables resuming incomplete verifications using the same ID

3. Reverification Linking

Connects reverification to original verification data

4. Webhook Correlation

Appears in all webhook events for tracking and correlation

Usage Patterns

Use Case	Pattern	Example
Need reverification	Stable customer ID	`cust_12345`
Need resume capability	Stable customer ID	`user_abc123`
Isolated attempts	Unique per attempt	`ver_${uuid}`

Consequences Matrix

Pattern	Initial Verification	Reverification	Resume	Webhook Tracking
Stable Customer ID	✅ Works	✅ Works	✅ Works	✅ Linked
Timestamp (default)	✅ Works	❌ Broken	❌ Broken	⚠️ Fragmented
UUID per attempt	✅ Works	❌ Broken	❌ Broken	⚠️ Fragmented

Recommended Patterns

✅ Recommended: Internal Customer ID

referenceId: 'customer_' + yourInternalCustomerId

Best for most use cases - stable, meaningful, and enables all features

✅ Recommended: Database Primary Key

referenceId: yourDatabasePrimaryKey.toString()

Simple mapping to your database records

✅ Recommended: Email Hash (for privacy)

referenceId: hashFunction(customerEmail)

Privacy-preserving option that remains stable

Problematic Patterns (Avoid)

❌ Avoid: Random UUID per attempt

referenceId: crypto.randomUUID() // Different each time!

Breaks reverification, resume, and correlation

❌ Avoid: Timestamp-based

referenceId: Date.now().toString() // Different each time!

Same problem as UUID - changes every time

❌ Avoid: Session IDs

referenceId: request.sessionId // Changes across sessions!

Fails when customer returns in new session

Code Examples

Initial Verification

// First time verifying this customer
await sdk.startVerificationWithCustomer('#container', {
  customerInfo: { /* ... */ },
  referenceId: 'customer_12345',  // Stable customer identifier
  onSuccess: (result) => {
    console.log('Verification completed!', result);
  }
});

Reverification (Returning Customer)

// MUST use same referenceId as original verification
await sdk.startReverification('#container', {
  referenceId: 'customer_12345',  // Same ID as original
  phoneNumber: '+1-555-123-4567',
  onSuccess: (result) => {
    console.log('Reverification completed!', result);
  }
});

Why the same ID? The system uses referenceIdto locate the original verification's document data for reuse.

Resuming Incomplete Verification

// User started but didn't complete address confirmation
// Using same referenceId automatically resumes
await sdk.startVerificationWithCustomer('#container', {
  customerInfo: { /* ... */ },
  referenceId: 'customer_12345',  // Same ID to resume
  onProgress: (event) => {
    // SDK detects existing incomplete verification and resumes
    console.log(`Resuming from ${event.step}`);
  }
});

FAQ

Q: Can I change referenceId after initial verification?

A: No. Once verification completes, referenceId is permanent for that verification record. You cannot retroactively change it.

Q: What if I use the same referenceId twice by accident?

A: With different customerInfo: Creates new verification, previous becomes "historical". For reverification: This is explicitly designed - reusing the ID links verifications together.

Q: Is referenceId visible to end users?

A: No. It's internal to your integration and appears only in webhook events and API responses to your backend.

Q: Can referenceId contain PII?

A: Technically yes, but NOT RECOMMENDED. Use hashed or anonymized identifiers instead for privacy best practices.

Decision Flowchart

Do you need reverification?
→ YES? Use stable customer identifier

Do you need resume capability?
→ YES? Use stable customer identifier

Need to isolate each attempt?
→ YES? Use unique ID per attempt

Default recommendation: Use stable customer identifier (most flexible)

customerInfo Fields

Required vs Optional Fields

Field	Required	Type	Description
`firstName`	Yes	string	Customer's first name
`lastName`	Yes	string	Customer's last name
`middleName`	Optional	string	Customer's middle name
`email`	Optional	string	Customer's email address
`phone`	Optional	string	Customer's phone number
`address`	Optional	ICustomerAddress	Customer's address object

Validation Constraints

firstName, lastName, middleName

Length: 1-100 characters
Blocked characters: < > ; & | $ \ "
Error:"contains invalid characters"

email

Pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
Error:"Invalid email format"

phone

Format: E.164 format recommended (+[country][number])
Validation: Uses libphonenumber-js library
Default Country: US (if no country code)
Error:"Invalid phone number format (must include country code)"

Code Example

const customerInfo = {
  firstName: 'John',       // Required, 1-100 chars
  lastName: 'Doe',         // Required, 1-100 chars
  middleName: 'Michael',   // Optional
  email: 'john.doe@example.com',  // Optional, validated format
  phone: '+1-555-123-4567',       // Optional, E.164 format
  address: {
    // See address fields section below
  }
};

address Fields (ICustomerAddress)

Field Requirements

Field	Required	Type	Description
`line1`	Yes	string	Primary address line (street address)
`line2`	Optional	string	Secondary address line (apt/unit number)
`locality`	Yes	string	City name
`minorAdminDivision`	Optional	string	County or minor administrative division
`majorAdminDivision`	Yes	string	State/province (2 uppercase letters)
`country`	Yes	string	Country code (ISO 3166-1 alpha-2)
`postalCode`	Yes	string	ZIP/postal code
`type`	Yes	string	Address type (e.g., 'residential', 'commercial')

Validation Constraints

majorAdminDivision (State)

Pattern: /^[A-Z]{2}$/
Format: Exactly 2 uppercase letters
Examples: CA, NY, TX, FL
Error:"State must be exactly 2 uppercase letters"

postalCode (US ZIP Code)

Pattern: /^[0-9]{5}(-[0-9]{4})?$/
Format: 12345 or 12345-6789
Error:"US ZIP Code must be in format 12345 or 12345-6789"

postalCode (Canada Postal Code)

Pattern: /^[A-Z][0-9][A-Z]\s?[0-9][A-Z][0-9]$/i
Format: A1A 1A1 or A1A1A1
Error:"Canadian Postal Code must be in format A1A 1A1"

Code Example

const address = {
  line1: '123 Main Street',          // Required
  line2: 'Apt 4B',                   // Optional
  locality: 'Springfield',           // Required (city)
  minorAdminDivision: 'Sangamon',    // Optional (county)
  majorAdminDivision: 'IL',          // Required (exactly 2 uppercase)
  country: 'US',                     // Required (ISO 3166-1 alpha-2)
  postalCode: '62701',               // Required (format depends on country)
  type: 'residential'                // Required
};

SDK Configuration Options

SDK Initialization (ISDKConfig)

Option	Type	Default	Description
`apiUrl`	string	(auto-detected)	API base URL
`deploymentStage`	DeploymentStage	`'sandbox'`	Environment: sandbox, production, preprod, nonprod
`bearerToken`	string	(required)	API authentication token
`timeout`	number	30000	Request timeout in milliseconds
`maxRetries`	number	3	Maximum retry attempts
`debug`	boolean	false	Enable debug mode
`logLevel`	string	`'info'`	Logging level: debug, info, warn, error

Verification Options (config object)

Option	Type	Default	Description
`mode`	string	`'embedded'`	UI display mode: modal or embedded
`qrCode`	boolean	false	Enable QR code for mobile handoff
`showSsnOnInitialForm`	boolean	true	Show SSN/National ID field
`tamperingBehavior`	string	`'warn'`	Field tampering response: warn or block

Reverification Options

Option	Type	Default	Description
`sendMessage`	boolean	true	Send SMS notification for mobile handoff

Default Values Summary

Quick reference for all default values when parameters are not explicitly provided.

Parameter	Default Value	Notes
`referenceId`	`customer_${Date.now()}`	Auto-generated if not provided (breaks reverification)
`deploymentStage`	`'sandbox'`	Safe default for testing
`timeout`	30000	Request timeout in milliseconds (30 seconds)
`maxRetries`	3	Automatic retry attempts
`mode`	`'embedded'`	UI display mode
`showSsnOnInitialForm`	true	Show National ID field
`tamperingBehavior`	`'warn'`	Field tampering response
`sendMessage`	true	SMS for reverification
`debug`	false	Debug mode disabled by default
`logLevel`	`'info'`	Default logging level

Best Practices

Always Provide referenceId

Never rely on the auto-generated timestamp-based default. Always explicitly provide a stable customer identifier.

referenceId: 'customer_' + yourInternalCustomerId // ✅ Good

Use E.164 Format for Phone Numbers

Include country code prefix to ensure proper validation and international support.

phone: '+1-555-123-4567' // ✅ Good (E.164 format)

Validate Before Submission

Client-side validation reduces failed API calls and improves user experience.

Use Sandbox for Testing

Test integrations in sandbox environment before deploying to production.

Vehicle Custody

Vehicle Custody

API Field Reference

Purpose of This Guide

referenceId (Critical)

Definition

Type & Format

Required vs Optional

The Auto-Generation Problem

Semantic Meaning

1. Identity Tracking

2. Session Resumability

3. Reverification Linking

4. Webhook Correlation

Usage Patterns

Consequences Matrix

Recommended Patterns

✅ Recommended: Internal Customer ID

✅ Recommended: Database Primary Key

✅ Recommended: Email Hash (for privacy)

Problematic Patterns (Avoid)

❌ Avoid: Random UUID per attempt

❌ Avoid: Timestamp-based

❌ Avoid: Session IDs

Code Examples

Initial Verification

Reverification (Returning Customer)

Resuming Incomplete Verification

FAQ

Q: Can I change referenceId after initial verification?

Q: What if I use the same referenceId twice by accident?

Q: Is referenceId visible to end users?

Q: Can referenceId contain PII?

Decision Flowchart

customerInfo Fields

Required vs Optional Fields

Validation Constraints

firstName, lastName, middleName

email

phone

Code Example

address Fields (ICustomerAddress)

Field Requirements

Validation Constraints

majorAdminDivision (State)

postalCode (US ZIP Code)

postalCode (Canada Postal Code)

Code Example

SDK Configuration Options

SDK Initialization (ISDKConfig)

Verification Options (config object)

Reverification Options

Default Values Summary

Best Practices

Always Provide referenceId

Use E.164 Format for Phone Numbers

Validate Before Submission

Use Sandbox for Testing

Related Documentation

SDK Documentation

Quick Start Guide

Webhook Events

Testing Guide