Web 3.0

Trulioo KYC Docs JavaScript SDK.

This package provides the hosted document verification UI flow for web applications. The SDK helps host applications:

initialize a verification flow with a shortcode
launch the Docs UI into an existing HTML element
receive completion and error callbacks
use Capture-powered document and selfie collection without building the full flow manually
support desktop-to-mobile handoff when configured on the transaction

For more information, see our Documentation.

Info

Some US states impose obligations on businesses that collect and use “biometric identifiers” and/or “biometric information”, which may include facial scan data extracted from photos during a document verification transaction. One such law is the Illinois Biometric Information Privacy Act (“BIPA”). A business required to comply with BIPA is under obligations to, among other things, ensure that it informs the individual of the purpose of the collection and obtain consent. Accordingly, we require a notice and consent mechanism be implemented for all document verification transactions, and our customers using our API must provide us with confirmation via API whether an individual is located in the United States and has consented to the transaction in the prescribed manner. We also strongly encourage all of our customers to consult with legal counsel to ensure their own compliance with such laws.

For more information about the required notice and consent mechanism, please refer to our Service Specific Terms for Document Verification.

Installation

npm install @trulioo/kyc-documents

Utilize the SDK from a CDN

In your project, you can import the Docs SDK directly from a CDN:

import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "https://cdn.jsdelivr.net/npm/@trulioo/kyc-documents/+esm";

You will now have access to the Docs SDK without adding the package through npm first.

The above URL will resolve to the latest version of the SDK. If you want to use a specific version instead, use:

import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "https://cdn.jsdelivr.net/npm/@trulioo/kyc-documents@VERSION_NUMBER/+esm";

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 by the Trulioo customer handoff flow
has an HTML element available for the Docs UI to render into
is ready to handle completion, validation, and exception callbacks
understands that transaction configuration such as locale, theme, and desktop-to-mobile behavior is driven by the Trulioo Customer API

Create an HTML element where the Docs UI should be rendered:

<div id="trulioo-sdk"></div>

Quick start

import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "@trulioo/kyc-documents";

const parentId = "trulioo-sdk";
const shortCode = "generated-from-trulioo-api";

const callbacks = new ListenerCallback({
  onComplete(success) {
    console.info("Verification completed:", success.transactionId);
  },
  onError(error) {
    console.error("Verification failed:", error.code, error.message);
  },
  onException(exception) {
    console.error("Unexpected verification exception:", exception.message);
  },
});

const events = new EventBuilder().setCallbacks(callbacks);
const trulioo = new Trulioo();

trulioo
  .initialize(shortCode)
  .then(() => {
    return trulioo.launch(parentId, events);
  })
  .then((result) => {
    console.info("Docs UI launched:", result);
  })
  .catch((error) => {
    console.error("Docs flow failed:", error);
  });

Typical flow

The standard host-side flow is:

Create a container element for the Docs UI.
Create optional callbacks for completion and error handling.
Create a Trulioo instance.
Call initialize(shortCode) to authorize the Docs flow.
Call launch(parentId, eventBuilder) to render the Docs UI.
Wait for completion or error callbacks from the flow.

The Docs SDK owns the full capture and submission experience. The host application is responsible for providing the shortcode, rendering container, and handling flow results.

Initialize the Docs flow

Use initialize(shortCode) to prepare the SDK for launch.

This is the first step of the Docs flow. A successful call authorizes the active transaction and returns the transaction id in the resolved result.

import { Trulioo } from "@trulioo/kyc-documents";

const trulioo = new Trulioo();

trulioo
  .initialize("generated-from-trulioo-api")
  .then((result) => {
    console.log("Initialized Docs transaction:", result.transactionId);
  })
  .catch((error) => {
    console.error("Failed to initialize Docs:", error);
  });

Launch the Docs UI

Use launch(parentId, eventBuilder) to attach the Docs UI to an existing element on the page.

The host application provides the element id where the UI should be rendered. The SDK then manages the full document verification flow inside that container.

import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "@trulioo/kyc-documents";

const trulioo = new Trulioo();

const callbacks = new ListenerCallback({
  onComplete(success) {
    console.log("Completed transaction:", success.transactionId);
  },
  onError(error) {
    console.error("Verification error:", error.code, error.message);
  },
  onException(exception) {
    console.error("Verification exception:", exception.message);
  },
});

const events = new EventBuilder().setCallbacks(callbacks);

trulioo
  .initialize("generated-from-trulioo-api")
  .then(() => trulioo.launch("trulioo-sdk", events))
  .then((result) => {
    console.log("Docs flow launched:", result);
  });

If launch(...) is called before initialize(...), the SDK is expected to reject. The host application should always initialize first and launch second for a new flow.

Handle completion and errors

Use ListenerCallback together with EventBuilder to receive flow events.

The host application can listen for:

onComplete when the verification flow finishes successfully
onError when the flow finishes with a handled product error
onException when an unexpected exception occurs

import {
  EventBuilder,
  ListenerCallback,
} from "@trulioo/kyc-documents";

const callbacks = new ListenerCallback({
  onComplete(success) {
    console.log("Success transaction:", success.transactionId);
  },
  onError(error) {
    console.error("Handled error:", error.code, error.message);
  },
  onException(exception) {
    console.error("Unexpected exception:", exception.message);
  },
});

const events = new EventBuilder().setCallbacks(callbacks);

This is the main integration point for the host application after launch. In most integrations, these callbacks are where the host decides whether to navigate, show a success state, retry, or log a failure.

Styling and asset loading

The SDK will import its required CSS automatically.

If the host application uses webpack, css-loader, or a similar bundling setup, make sure the CSS files inside @trulioo/kyc-documents are not excluded from the application build configuration.

Customization

The SDK supports customization options such as locale and theme configuration.

These options are not configured directly in the JavaScript SDK surface. They are configured through the Trulioo Customer API when the transaction is created. Once the shortcode is provided to the SDK, the Docs UI renders using the configuration already associated with that transaction.

For details on how to configure these options, see the Customer API documentation.

Desktop to mobile workflow

The Docs SDK supports cross-device document capture when desktop-to-mobile is enabled for the transaction.

In that flow:

an end user starts verification on a desktop browser
the Docs SDK displays a QR code
the end user scans the QR code with a mobile phone
document capture continues on the mobile device
after capture is completed on mobile, the desktop flow continues automatically

This allows the host application to launch a desktop verification experience even when document capture is expected to happen on a mobile device.

For details on how to configure desktop-to-mobile behavior, see the Customer API documentation.