Trulioo Web SDK Guide

Quick Summary

The Trulioo Web SDK initializes a shortcode-backed session and exposes base verification capabilities for browser applications.

Customer applications can expect the SDK to:

• initialize an authorized session from a shortcode
• support configured Device Intelligence and eID capabilities
• return capability results, errors, and diagnostic information
• leave journey decisions and customer policy to the host application

A standard web integration looks like this:

1. install @trulioo/trulioo
2. initialize with a shortcode
3. start the required capability: Device Intelligence or eID
4. use the result to continue, retry, or route the journey for review

Installation

npm install @trulioo/trulioo

Example import:

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

Use the SDK from a CDN:

import { Trulioo } from "https://cdn.trulioo.com/web/sdk/trulioo/latest/dist/esm/trulioo.js";

Use a pinned version instead of the latest package:

import { Trulioo } from "https://cdn.trulioo.com/web/sdk/trulioo/VERSION_NUMBER/dist/esm/trulioo.js";

Replace VERSION_NUMBER with the SDK version you want to lock to.

Before You Start

Before using the SDK, make sure the host application:

• has a valid shortcode generated through the Trulioo customer handoff flow using the Customer API 3.0 handoff operation
• uses a shortcode configured for the capabilities required by the journey, such as Device Intelligence or eID
• initializes a new SDK session for each verification journey

Initialization

Initialize once with the shortcode before starting a verification capability:

const initialized = await Trulioo.initialize(shortcode);

initialized is a TruliooInitializationResult for the current verification journey. Retain it only while that journey is active.

What Initialization Does

Initialization:

1. resolves the service host from the shortcode
2. establishes an authorized SDK session
3. retrieves the session configuration
4. when Device Intelligence is enabled, loads the managed device runtime
5. returns the initialization result for the current verification journey

Initialization Result

initialize(...) returns the current TruliooInitializationResult.

| Field | Type | Meaning | |---|---|---| | transactionId | string | Identifier for the verification journey. | | debugTrace | TruliooDebugTraceEntry[] \| undefined | SDK diagnostic entries for support and troubleshooting. |

The SDK retains the session configuration, resolved service host, and authorization token internally for the active session. Call reset() to clear that session before starting another journey.

Verification Capabilities

Beta - changes are possible.

After initialization, start the capability required by the current verification journey. Availability is determined by the shortcode configuration.

Device Intelligence

Use Device Intelligence when the verification journey needs a device-risk result before deciding the next step.

Choose An Integration Mode

| API | Use when | Returns | |---|---|---| | collectDeviceIntelligence(...) | The application needs to wait for the device-event lifecycle status. | A lifecycle-only deviceEvent and debugTrace. | | sendDeviceInformation(...) | DI should be submitted in the background without waiting for lifecycle processing. | An accepted or failed submission receipt. |

Recommended: collectDeviceIntelligence(...)

For most integrations, use collectDeviceIntelligence(...). It performs collection, submission, and polling in one Promise-based call. It returns a terminal event when processing completes or fails; if the configured polling limit is reached first, it returns the latest non-terminal lifecycle event and records the timeout in debugTrace.

If polling exhausts, the result contains the last non-terminal lifecycle state and debugTrace contains a device_event_terminal timeout entry. Wait and retrieve the detailed result only after the status is COMPLETED. If the event fails, use deviceEvent.failureReason for the failure detail.

1. initialize once
2. call collectDeviceIntelligence(...)
3. use a completed deviceEvent to continue the journey

Explicit collection example:

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

const initialized = await Trulioo.initialize(shortcode);

const result = await Trulioo.collectDeviceIntelligence();

if (result.deviceEvent?.status === DeviceEventStatus.Completed) {
  const { eventId, transactionId } = result.deviceEvent;
}

collectDeviceIntelligence(...) returns an enriched TruliooInitializationResult for the same session.

| Field | Type | Meaning | |---|---|---| | deviceEvent | DeviceEventResult \| undefined | Device-event lifecycle result, when Device Intelligence was collected. | | deviceEvent.eventId | string | Identifier for the submitted device event. | | deviceEvent.transactionId | string | Identifier used to retrieve the detailed device result after processing completes. | | deviceEvent.status | DeviceEventStatus | Current device-event state: queued, running, completed, or failed. | | deviceEvent.failureReason | string \| undefined | Failure explanation when the device event fails. | | debugTrace | TruliooDebugTraceEntry[] \| undefined | SDK diagnostic entries for troubleshooting. |

When deviceEvent.status is COMPLETED, use deviceEvent.transactionId to retrieve the detailed result. To retrieve the detailed result, see Retrieve the Detailed Result.

Background Submission: sendDeviceInformation(...)

Use sendDeviceInformation(...) when the application should submit DI without waiting for server evaluation or a final risk result.

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

const initialized = await Trulioo.initialize(shortcode);

const submission = await Trulioo.sendDeviceInformation();

if (submission.status === TruliooSendDeviceInformationStatus.Accepted) {
  console.log(submission.transactionId, submission.eventId);
} else {
  console.error(submission.error.code, submission.error.message);
}

The submission result is one of two shapes.

Accepted Response Fields

| Field | Type | Meaning | |---|---|---| | status | TruliooSendDeviceInformationStatus.Accepted | Trulioo accepted the device-event submission. Evaluation may still be processing. | | transactionId | string | Transaction identifier for the submitted device event. | | eventId | string | Device-event identifier for the submitted device event. | | debugTrace | TruliooDebugTraceEntry[] | SDK diagnostic entries captured while collecting and submitting the payload. |

Failed Response Fields

| Field | Type | Meaning | |---|---|---| | status | TruliooSendDeviceInformationStatus.Failed | The SDK could not initialize the runtime, collect the payload, or submit the device event. | | error.code | TruliooSendDeviceInformationFailureCode | Stable failure code. | | error.stage | string | SDK stage at which the failure occurred. | | error.message | string | Failure detail. | | error.debugTrace | TruliooDebugTraceEntry[] | SDK diagnostic entries captured before the failure. |

sendDeviceInformation(...) is designed for receipt-based background submission. It returns after Trulioo accepts the event, rather than waiting for a final DI outcome.

Neither DI integration mode returns the detailed device result. Use the returned transaction ID with Retrieve the Detailed Result after processing completes.

Retrieve the Detailed Result

Both integration modes provide transactionId after submission. Call GET /transactions/{transactionId}/devices with that value after device processing is complete to retrieve the detailed device result.

• collectDeviceIntelligence(...) normally resolves after reaching completed or failed. If its configured polling limit is reached first, it resolves with the latest non-terminal lifecycle state and records the timeout in debugTrace.
• sendDeviceInformation(...) returns accepted before evaluation completes.

Retrieve details after the event is completed. If collectDeviceIntelligence(...) returns a non-terminal status, wait and retry the endpoint until processing completes.

See Get transaction devices for authentication, request requirements, and the detailed result fields.

Device Intelligence Options

Device Intelligence options customize explicit DI collection. They are optional; the SDK manages the device runtime automatically.

collectDeviceIntelligence(...) accepts optional polling controls:

| Option | Type | Use | |---|---|---| | polling | DeviceIntelligencePollingOptions | Controls how long explicit collection waits for a terminal result. Defaults to 32 attempts, 1,250 ms apart. If the event remains non-terminal after the limit, the result contains the last lifecycle-only deviceEvent and records the timeout in debugTrace. |

Provide options directly to explicit collection:

const result = await Trulioo.collectDeviceIntelligence({
  polling: {
    maxAttempts: 10,
    intervalMs: 1000,
  },
});

eID Verification

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

Start a Verification

eID has one standard flow:

1. initialize once
2. call Trulioo.verifyEid(...) from the customer's continue action
3. inspect the terminal result

verifyEid(...) uses the session established by initialize(...). It prepares the provider session automatically when needed, opens the interactive provider flow, and waits for the backend result.

Call it directly from a user action. Browsers can block a provider popup or tab that is opened outside a user gesture.

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

const initialized = await Trulioo.initialize(shortcode);

try {
  const result = await Trulioo.verifyEid({
    countryCode: "CA",
  });

  if (result.outcome === "SUCCESS" && result.match) {
    console.log("eid verified", result.transactionId);
  } else {
    console.log("eid not verified", result);
  }
} catch (error) {
  // The provider flow could not complete, for example because the popup was
  // blocked, the customer cancelled, the flow timed out, or a request failed.
  console.error("eid verification failed", error);
}

Result

When the provider flow completes and backend polling produces a result, verifyEid(...) resolves with an EidVerificationResult. The result does not contain the customer's submitted identity data. Browser-flow, preparation, and network failures reject the promise instead.

| Field | Type | Meaning | |---|---|---| | transactionId | string | Trulioo transaction that owns the verification. | | outcome | EidOutcome | Terminal eID outcome: SUCCESS, FAILED, TIMEOUT, ERROR, or CANCELLED. | | match | boolean | Whether the configured eID verification matched successfully. |

Apply the host application's policy to the result. For example, continue after SUCCESS with match: true; provide a retry or alternate journey for other results and caught errors.

Retrieve the Detailed Result

After verifyEid(...) reaches a terminal result, call GET /transactions/{transactionId}/eid/result with result.transactionId to retrieve the detailed eID result.

See Get eID result for authentication, request requirements, and the detailed result fields.

Input

import type { EidVerificationConfig } from "@trulioo/trulioo";

const input: EidVerificationConfig = {
  countryCode: "CA",
  // providerIdentifier: "provider-id", // optional provider pin
};

| Input | Type | Format and behavior | |---|---|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | countryCode | string | Required. Use the two-letter uppercase ISO 3166-1 alpha-2 code configured for the eID journey examples: "SE" for Sweden, "CA" for Canada, or "US" for the United States. Server-side configuration determines whether eID is available for the provided country. | | providerIdentifier | string | Optional. Omit it for server-side provider selection; set it only when the journey intentionally pins a licensed provider. |

Optional: Choosing a specific Provider

Provider discovery is optional. When providerIdentifier is omitted, Trulioo selects the healthiest licensed provider for the configured country. Call listEidProviders(...) only when the application needs to show a provider picker.

const providers = await Trulioo.listEidProviders("CA");

const result = await Trulioo.verifyEid({
  countryCode: "CA",
  providerIdentifier: providers[0]?.id,
});

| Provider field | Type | Meaning | |---|---|---| | id | string | Provider identifier. Pass this value as providerIdentifier after the customer chooses it. | | name | string | Display name suitable for the picker. | | countries | string[] | Countries supported by the provider. | | health | string | Current provider health. |

To restart an interrupted eID flow, call Trulioo.reset() and initialize a new session.

Resetting State

Call Trulioo.reset() to clear all internal session state. Use this for logout flows, multi-session apps, or when re-initializing with a new shortcode:

Trulioo.reset();
// Can now call Trulioo.initialize(...) again with a new shortcode

reset() clears the internally stored session and resets cached eID state. Reinitialize before starting another session.

Session-backed methods throw TruliooNotInitializedError after reset: listEidProviders(...) and verifyEid(...). Device Intelligence methods receive an explicit initialization result; do not reuse a previous result after reset—initialize again instead.

Error Handling

Not-initialized errors:

• TruliooNotInitializedError is thrown by session-backed methods when called before initialize() completes or after reset()
• Affected methods: listEidProviders and verifyEid.

Initialization errors:

• reject the initialization promise

Send errors:

• resolve with { status: TruliooSendDeviceInformationStatus.Failed, error: { code, stage, message, debugTrace } }

eID errors:

• verifyEid(...) rejects when preparation, provider handoff, callback handling, or result polling fails
• It also rejects when the customer cancels, the provider flow times out, the browser blocks the popup, or another eID verification is already in progress

Collection errors:

• resolve with the unchanged initialization result when Device Intelligence is not enabled for the session
• reject the collection promise when device-runtime initialization, payload submission, device-event seeding, or a polling request fails
• resolve with the latest lifecycle-only deviceEvent when polling reaches its limit before a terminal status; inspect the returned debugTrace for the timeout entry

Troubleshooting

If Device Intelligence does not appear:

1. Confirm initialization completed successfully.
2. Confirm Device Intelligence is enabled for the account and verification journey.
3. Confirm you explicitly called collectDeviceIntelligence(...) or sendDeviceInformation(...).
4. Inspect debugTrace.

If results are incomplete:

1. Inspect deviceEvent?.failureReason.
2. Inspect debugTrace for a polling timeout or failed stage.
3. After the event completes, retrieve the detailed result with GET /transactions/{transactionId}/devices.

If eID does not start or complete:

1. Confirm initialization completed successfully and the selected country is configured for eID.
2. Call verifyEid(...) directly from the customer's action so the browser can open the provider flow.
3. Inspect a resolved result's outcome and match, or handle the rejected error when the provider flow, callback, or result polling fails.
4. Call reset(), initialize a new session, then retry an interrupted eID flow.