Trulioo SDK - Web Guide

npm install @trulioo/trulioo

import { Trulioo } from "@trulioo/trulioo";

A standard integration looks like this:

1. Get a shortcode from your backend for the active transaction.
2. Call Trulioo.initialize(shortcode).
3. Call Trulioo.sendDeviceInformation(...).
4. Optionally include subject reference data (name, date of birth, etc.).
5. Branch on accepted or failed and log transactionId, eventId, and debugTrace.

What This SDK Covers

The base Trulioo web SDK provides three verification flows:

• Device Intelligence — via sendDeviceInformation(...), collectDeviceIntelligence(...), and getDeviceInformation(...)
• KYC Data verification — via verifyData(...)
• eID verification — via prepareEid(...) and verifyEid(...)

Initialization

Call Trulioo.initialize(shortcode) before any other SDK operation. Initialization resolves the session, authorizes it against Trulioo APIs, and fetches the configuration for your transaction.

const initialized = await Trulioo.initialize(
  shortcode,
  {
    onComplete(result) {
      // Optional: called when initialization completes
    },
    onError(error) {
      // Optional: called if initialization fails
    },
  },
  {
    allowLocalDevelopment: false,
    sdkVersion: "1.0.0",
  },
);

Initialization does not automatically trigger device event collection unless you explicitly enable web auto-collection.

Initialization options (TruliooInitializationOptions):

Note: TruliooDeviceIntelligenceOptions also accepts a userId field. Use this only when your downstream device-intelligence runtime expects a runtime-specific user identifier. It is not a replacement for the Trulioo transaction ID or event ID.

Device Intelligence

Use Device Intelligence to collect device-risk telemetry from the current browser session.

Standard Integration (Recommended)

For most integrations, use sendDeviceInformation(...). This is a fire-and-forget send — it submits the device event and returns a terminal result.

const initialized = await Trulioo.initialize(shortcode);

const result = await Trulioo.sendDeviceInformation(initialized, {
  reference: {
    firstName: "Jane",
    lastName: "Doe",
    dateOfBirth: "1990-01-01",
  },
});

if (result.status === "accepted") {
  console.log(result.transactionId, result.eventId);
} else {
  console.error(result.error.code, result.error.stage, result.error.message);
}

Debug Integration

Use collectDeviceIntelligence(...) only when you need the resolved device event and normalized seed for diagnostics or debug tooling.

const initialized = await Trulioo.initialize(shortcode);

const debugResult = await Trulioo.collectDeviceIntelligence(initialized, {
  polling: {
    maxAttempts: 32,
    intervalMs: 1250,
  },
  reference: {
    firstName: "Jane",
    lastName: "Doe",
  },
});

console.log(debugResult.deviceEvent);
console.log(debugResult.deviceSeed);

Callback-Only (Normalized Seed)

If you only need the normalized device result in a callback:

Trulioo.getDeviceInformation(
  initialized,
  (device) => {
    // device is DeviceSeedResponse | undefined
  },
  (error) => {
    // Collection failed
  },
);

Key behaviors to know:

• sendDeviceInformation(...) is the standard production path.
• collectDeviceIntelligence(...) is a blocking debug path — do not use it in production unless you specifically need the terminal event.
• reference is caller-supplied subject data only. The SDK generates device basic information internally — do not attempt to pass those fields yourself.
• The SDK requires the encrypted payload bundle before seeding the Trulioo device event. A runtime path that skips this step is unsupported.

Optional Web Auto-Collection

The web SDK can queue device collection automatically during initialization when either of these is provided:

• handlers.onDeviceInformation
• options.deviceIntelligence

Enable this intentionally. If you pass deviceIntelligence options without meaning to, auto-collection will run in the background. For the closest parity with native platform behavior, prefer explicit collection via sendDeviceInformation(...).

Default polling settings:

KYC Data Verification

Use verifyData(...) when your flow has subject data and needs a terminal KYC verification result from the same session.

const initialized = await Trulioo.initialize(shortcode);

const stopDataState = Trulioo.onDataStateChange((state) => {
  console.log("dataState", state);
});

const result = await Trulioo.verifyData({
  countryCode: "CA",
  personInfo: {
    firstName: "Jane",
    lastName: "Doe",
    dateOfBirth: "1990-01-01",
  },
  location: {
    buildingNumber: "123",
    streetName: "Example",
    streetType: "Ave",
    city: "Exampleville",
    stateProvinceCode: "BC",
    postalCode: "V0V0V0",
  },
  communication: {
    emailAddress: "[email protected]",
    mobileNumber: "+12025550123",
  },
});

stopDataState();

if (result.outcome === "ACCEPT" && result.recordMatch) {
  console.log("data verified", result.transactionId);
} else {
  console.log("review path", result);
}

Key behaviors to know:

• verifyData(...) reuses the internally stored initialized session — you do not pass initialized to it directly.
• The SDK submits PII but does not return PII in DataVerificationResult.
• Trulioo.onDataStateChange(...) lets your UI react to state changes during verification.
• Trulioo.resetData() cancels or clears the current data flow if you need to restart it.

eID Verification

Use the eID entrypoints when your flow needs an interactive, provider-backed identity verification from the same initialized session.

const initialized = await Trulioo.initialize(shortcode);

const stopEidState = Trulioo.onEidStateChange((state) => {
  console.log("eidState", state);
});

await Trulioo.prepareEid({
  transactionId: initialized.configuration.transactionId,
  countryCode: "SE",
});

const eidResult = await Trulioo.verifyEid({
  transactionId: initialized.configuration.transactionId,
  countryCode: "SE",
});

stopEidState();

if (eidResult.outcome === "SUCCESS" && eidResult.match) {
  console.log("eID verified", eidResult.transactionId);
} else {
  console.log("eID not verified", eidResult);
}

Key behaviors to know:

• prepareEid(...) pre-warms the eID screen before the user launches the provider flow. Call it when the eID screen becomes visible.
• verifyEid(...) opens the interactive provider flow and waits for a terminal result.
• transactionId must come from initialized.configuration.transactionId.
• providerIdentifier is optional — only pass it when your flow needs to pin a specific provider.
• callbackOrigin is optional — only set it when your hosted callback flow requires an explicit origin override.
• Trulioo.resetEid() clears interrupted eID state before a restart.

Advanced: Authorized Session Client

After initialization, you can access approved Trulioo routes directly using Trulioo.sessionClient(...). Use this for typed authorized requests or binary uploads.

const sessionClient = Trulioo.sessionClient(initialized, {
  allowedEndpoints: ["/vendor/device/session", "/vendor/device/upload"],
});

Available operations:

Typed POST example:

type StatusResponse = { status: string };

const status = await sessionClient.authorizedPost<{ transactionId: string }, StatusResponse>(
  { path: "/vendor/device/session" },
  { transactionId: "txn-123" },
);

Upload example:

const response = await sessionClient.authorizedUpload<{ transactionId: string }>(
  { path: "/vendor/device/upload" },
  imageBytes,
  {
    headers: { "Content-Type": "image/jpeg" },
  },
);

Rules:

• Initialize first and reuse the returned initialized result.
• Register any routes beyond the base SDK defaults explicitly via allowedEndpoints.
• Use approved relative paths only.
• The session client manages the bearer token — do not pass accessToken manually into these calls.
• Handle TruliooApiError for non-2xx responses.
• This is an advanced contract. For standard device intelligence, use sendDeviceInformation(...).

Subject Reference Data

Pass caller-owned subject data using the reference field:

const reference = {
  firstName: "Jane",
  lastName: "Doe",
  dateOfBirth: "1990-01-01",
  phoneNumber: "+15551234567",
  other: [{ customKey: "middleName", value: "Ann" }],
};

Do not pass device basic-information fields from your application. The SDK builds those internally. A runtime submit that does not return the encrypted payload bundle fails before Trulioo seed submission.

Results

TruliooInitializationResult contains:

Error Handling

Environments and Shortcodes

Environment is resolved from the shortcode — you do not set it manually.

Supported region prefixes: us, eu, ap / apac, ca

Local and emulator shortcodes are blocked unless allowLocalDevelopment: true is set in initialization options.

Common Mistakes

Assuming auto-collection is always on. Auto-collection only runs when handlers.onDeviceInformation or options.deviceIntelligence is provided to initialize(...). If you expect explicit send behavior, do not pass those options.

Accidentally enabling auto-collection. Passing deviceIntelligence options without intending to triggers background collection. Review your initialization options carefully.

Treating reference failure as a terminal event failure. A failed subject reference submission is recorded in debugTrace but does not fail the device event itself. Check both separately.

Passing device basic-information from your app. The SDK generates these fields. Supplying them yourself will cause a runtime failure before seed submission.

Using local shortcodes without enabling local development. Local and emulator shortcodes are blocked by default. Set allowLocalDevelopment: true explicitly.

Troubleshooting

Device intelligence is not appearing:

1. Confirm initialization completed successfully.
2. Confirm configuration.deviceIntelligence?.enabled === true.
3. Confirm the browser can load the configured device-intelligence runtime.
4. Confirm you either explicitly called sendDeviceInformation(...) or intentionally enabled auto-collection.
5. Inspect debugTrace.

Results are incomplete:

• Inspect deviceEvent?.failureReason.
• Inspect processor status if present.
• Compare the terminal event outcome to device_reference_submit.

Diagnostic Checklist

When filing a support issue, include:

• The shortcode environment (production, development, preview, local, or emulator).
• Which integration path was used: fire-and-forget send, blocking debug collection, or intentional auto-collection.
• Whether loadBundledDeviceBridge was enabled or the default runtime path was used.
• The terminal deviceEvent.status and failureReason, if present.
• transactionId, eventId, and relevant debugTrace entries.
• Whether subject reference data was provided and whether device_reference_submit succeeded.
• Browser name, browser version, and any custom runtime overrides applied.

Public API Reference

Main entry points:

Trulioo.initialize(...) · Trulioo.sendDeviceInformation(...) · Trulioo.collectDeviceIntelligence(...) · Trulioo.getDeviceInformation(...) · Trulioo.verifyData(...) · Trulioo.prepareEid(...) · Trulioo.verifyEid(...) · Trulioo.sessionClient(...)

Key types:

TruliooInitializationOptions · TruliooInitializationHandlers · TruliooInitializationResult · TruliooSessionClient · TruliooSessionClientOptions · TruliooDeviceIntelligenceOptions · TruliooSendDeviceInformationOptions · TruliooSendDeviceInformationResult · DeviceIntelligencePollingOptions · DeviceSubjectReference · TruliooDebugTraceEntry · DeviceReferenceOtherField · AuthorizedPostEndpoint · TruliooApiError