SDK reference

PersonaBlocks.create() is the single entry point of the vanilla Web SDK: pass it your session token and configuration, and it returns an instance you control with methods like open() and close().

Callbacks (onComplete, onError, and friends) fire as the underlying session progresses, and onError receives a typed error — an expired token, a blocked popup, a lost connection, and similar conditions — with a recoverable flag so you can handle each distinctly in your product.

create(options)

create() validates its options synchronously and returns a PBInstance. Only clientToken is required.

Options

Option	Type	Default	Description
clientToken	string	— (required)	The pbvs_... session token minted by your backend via the /v1 API.
flow	'auto' | 'wallet' | 'phone'	'auto'	Which rail to open: 'phone' → iframe, 'wallet' → popup, 'auto' → a built-in chooser the customer picks from.
container	HTMLElement | string | null	document.body	Mount point for the iframe/chooser overlay — an element, a CSS selector, or omitted (a viewport-fixed overlay on document.body). Ignored by the popup and redirect venues.
appearance	PBAppearance	—	Theme, variables, and rules for the hosted flow. See Theming.
hostOrigin	string	auto-derived	Override the auto-derived host origin. Testing / non-standard hosting only — production integrations should never set it.
pollIntervalMs	number	3000	Poll interval (ms) for the popup/redirect venue’s session-status poll.

Callbacks

All callbacks are optional. Each is wrapped so a throw inside your handler can never break the verification flow.

Callback	Signature	Fires when
onReady	() => void	The instance has been created and is ready to open().
onComplete	(result) => void	The session reached a terminal success. result is { sessionId, vicId, method } — IDs only.
onCancel	({ resumeToken }) => void	The customer backed out. resumeToken is the same clientToken you already hold — re-create() with it to resume. Cancel is not an error.
onError	(error) => void	A typed error occurred. error is { type, recoverable, message } (see Errors).
onEvent	(name, metadata) => void	An advisory lifecycle event. Two positional args, not one object. Names emitted today: 'state' and 'resize'.

Caution

onComplete carries IDs only — no tier, verdict, score, or decisioning data ever rides it. To read a verification’s outcome, use your server-side webhook (verification_session.completed) or the /v1 API. Never make a pass/fail decision from the browser.

The instance

create() returns a PBInstance with four methods:

Method	Behavior
open()	Opens the resolved venue. For the popup (wallet) venue this must be called synchronously from a user gesture (a click handler) or the browser’s popup blocker engages.
close()	Tears down the open UI and stops polling, but leaves the instance reusable — you can open() it again.
destroy()	Terminal teardown: like close(), but marks the instance dead. Any later open() throws. Called automatically on expired_token/invalid_token.
redirect()	Full-page navigation to the hosted /verify/:token flow. Always available (even before open()) — this is the recovery path after popup_blocked.

Note

Calling open() again while a venue is already mounted (e.g. a double-click) logs a warning and no-ops — it never attaches a second listener or double-fires onComplete. open() works again after any terminal outcome (complete, cancel, error) or an explicit close().

Errors

Every onError receives exactly one PBErrorType. Branch on the recoverable flag — it tells you whether a retry is meaningful — rather than hard-coding behavior per string. message, when present, is always sanitized (never a raw exception or stack trace).

type	Recovery
invalid_token	The token isn’t a live session. The instance is destroyed automatically — mint a fresh session and create() again.
expired_token	The session TTL elapsed (recoverable: false). The instance is destroyed automatically; same recovery as above.
popup_blocked	The wallet popup was blocked (recoverable: true). Call redirect() to continue in the current tab.
wallet_unavailable	No wallet is available for the wallet rail. Offer the phone rail or redirect().
no_camera	No usable camera is available for capture.
permissions_unavailable	Camera or microphone permission was denied or is unavailable.
network	A status poll or load failed transiently (recoverable: true) — the SDK keeps polling, and retrying is safe.
exception	An unexpected failure; message is sanitized.

What to read next

• Theming — the appearance variables and rules.
• Venues — how each flow behaves at runtime.
• Webhooks — where the verification verdict actually lives.