Skip to main content
Access these methods via client.sessions. They manage hosted verification sessions. Request and response schemas are documented in full on the linked REST endpoints — this page covers the SDK signatures, types, and examples.

​
create(input)

create(input: SessionCreateInput): Promise<SessionCreateResult>
Create a hosted verification session.
ParameterTypeRequiredDescription
input.firstNamestringYesApplicant’s first name
input.lastNamestringYesApplicant’s last name
input.emailstringYesApplicant’s email address
input.phonestringYesApplicant’s phone number (E.164)
input.externalIdstringNoYour internal reference ID
input.workflowIdstringNoWorkflow to run
input.redirectUrlstringNoURL to redirect the user to after verification
input.sendEmailInvitebooleanNoSend an email invitation
input.sendPhoneInvitebooleanNoSend an SMS invitation
Returns SessionCreateResult: 
interface SessionCreateResult {
  id: string;
  sessionUrl: string;
  externalId?: string;
  links: Array<{ url: string; type: string }>;
}
Throws ValidationError, AuthenticationError, RateLimitError, DeepIDVError. 
const session = await client.sessions.create({
  firstName: 'Jane',
  lastName: 'Doe',
  email: 'jane@example.com',
  phone: '+15551234567',
  redirectUrl: 'https://yourapp.com/done',
});

console.log(session.sessionUrl);
See also: REST Create Session.

​
retrieve(sessionId)

retrieve(sessionId: string): Promise<SessionRetrieveResult>
Retrieve full session details, including analysis results.
ParameterTypeRequiredDescription
sessionIdstringYesSession ID from create()
Returns SessionRetrieveResult: 
interface SessionRetrieveResult {
  sessionRecord: Session;
  user?: {
    id: string;
    email: string;
    firstName: string;
    lastName: string;
    phone: string;
    createdAt: string;
    updatedAt: string;
  };
  senderUser?: { /* same shape as user */ };
  resourceLinks?: Record<string, string>;
}
sessionRecord is the full Session object — it carries status, sessionProgress, and an analysisData block with the document OCR, face-match, and liveness results. See Navigating analysis data for the walkthrough. Throws ValidationError, AuthenticationError, NotFoundError, DeepIDVError. 
const result = await client.sessions.retrieve('session-id-123');
console.log(result.sessionRecord.status); // "SUBMITTED"
See also: REST Retrieve Session.

​
list(params?)

list(params?: SessionListParams): Promise<PaginatedResponse<Session>>
List sessions with optional filtering and pagination.
ParameterTypeRequiredDescription
params.limitnumberNoMax results per page
params.offsetnumberNoStarting offset
params.statusSessionStatusNoFilter: PENDING, SUBMITTED, VERIFIED, REJECTED, VOIDED
Returns PaginatedResponse<Session>: 
interface PaginatedResponse<T> {
  data: T[];
  total?: number;
  hasMore?: boolean;
  limit: number;
  offset: number;
}

const page = await client.sessions.list({ status: 'SUBMITTED', limit: 10 });
for (const session of page.data) {
  console.log(`${session.id}: ${session.status}`);
}
See also: REST List Sessions.

​
updateStatus(sessionId, status)

updateStatus(
  sessionId: string,
  status: 'VERIFIED' | 'REJECTED' | 'VOIDED',
): Promise<SessionRetrieveResult>
Set the final review status. Only VERIFIED, REJECTED, and VOIDED are valid targets — PENDING and SUBMITTED are managed by the API.
ParameterTypeRequiredDescription
sessionIdstringYesSession ID
status'VERIFIED' | 'REJECTED' | 'VOIDED'YesNew status
Returns SessionRetrieveResult — the updated session details. Throws ValidationError (invalid status), AuthenticationError, NotFoundError, DeepIDVError. 
await client.sessions.updateStatus('session-id-123', 'VERIFIED');
See also: REST Update Session Status. 
type SessionStatus = 'PENDING' | 'SUBMITTED' | 'VERIFIED' | 'REJECTED' | 'VOIDED';
type SessionStatusUpdate = 'VERIFIED' | 'REJECTED' | 'VOIDED';

interface SessionCreateInput {
  firstName: string;
  lastName: string;
  email: string;
  phone: string;
  externalId?: string;
  workflowId?: string;
  redirectUrl?: string;
  sendEmailInvite?: boolean;
  sendPhoneInvite?: boolean;
}

interface SessionListParams {
  limit?: number;
  offset?: number;
  status?: SessionStatus;
}