@trulioo/kyc-documents

Audience And Scope

Use this guide when integrating the hosted Trulioo KYC Documents flow into a web application.

This guide covers the public npm package, CDN entrypoint, shortcode initialization, hosted UI launch, callback handling, and transaction-owned configuration.

If you are already using the legacy DocV Web 2.x SDK, read KYC Documents Web 3.0 Migration Guide before applying the current integration steps in this document.

Quick Summary

The Trulioo KYC Documents Web SDK provides a hosted document verification flow for web applications.

Customer applications can expect the SDK to:

• initialize a shortcode-backed document verification transaction
• launch hosted document and selfie capture screens into an existing HTML element
• apply transaction configuration resolved for the active shortcode
• handle capture, image verification, acceptance, and submission inside the hosted flow
• return completion, validation, and exception callbacks for host routing and support
• support desktop-to-mobile handoff when configured on the transaction

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

If your existing integration still uses @trulioo/docv, @trulioo/docv-csp, Trulioo.workflow(), or Trulioo.initialize(workflowOption), use KYC Documents Web 3.0 Migration Guide to update the package, initialization, and event wiring first.

Utilize the SDK from a CDN

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

import {
  Trulioo,
  EventBuilder,
  ListenerCallback,
} from "https://cdn.trulioo.com/web/sdk/kyc-documents/latest/kyc-documents.mjs";

You will now have access to the KYC Documents 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.trulioo.com/web/sdk/kyc-documents/VERSION_NUMBER/kyc-documents.mjs";

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 through the Customer API 3.0 handoff operation
• has an HTML element available for the KYC Documents 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 KYC Documents 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("KYC Documents UI launched:", result);
  })
  .catch((error) => {
    console.error("KYC Documents flow failed:", error);
  });

Typical flow

The standard host-side flow is:

1. Create a container element for the KYC Documents UI.
2. Create optional callbacks for completion and error handling.
3. Create a Trulioo instance.
4. Call initialize(shortCode) to authorize the KYC Documents flow.
5. Call launch(parentId, eventBuilder) to render the KYC Documents UI.
6. Wait for completion or error callbacks from the flow.

The KYC Documents 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 KYC Documents flow

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

This is the first step of the KYC Documents 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 KYC Documents transaction:", result.transactionId);
  })
  .catch((error) => {
    console.error("Failed to initialize Docs:", error);
  });

Launch the KYC Documents UI

Use launch(parentId, eventBuilder) to attach the KYC Documents 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("KYC Documents 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 KYC Documents UI renders using the configuration already associated with that transaction.

For details on how to configure these options, see the Customer API 3.0 transaction operation.

Desktop to mobile workflow

The KYC Documents 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 KYC Documents 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 3.0 transaction operation.