Trulioo KYC Documents Capture SDK — Web

The KYC Documents Capture SDK gives your organization full control over the document and selfie capture experience. You own the UI, branding, and flow; Trulioo provides the underlying image capture and verification technology.

Build capture experiences that align with your brand guidelines, with custom overlays, animations, and messaging, while relying on Trulioo's built-in verification intelligence for accuracy and security.

Looking for a ready-made solution? Use the KYC Documents SDK instead. It provides the same capture and verification technology with a complete Trulioo-designed UI and minimal setup.

Quick Summary

The KYC Documents Capture Web SDK lets your application own the surrounding user experience while the SDK manages camera capture and image verification.

Standard Capture Flow

1. Install @trulioo/kyc-documents-capture.
2. Get a shortcode from your backend for the active transaction.
3. Call initializeCapture(shortCode) and wait for it to resolve.
4. Create a document or selfie camera with createCaptureCamera(config?).
5. Render the camera into an existing DOM element.
6. Use startFeedback() for auto capture or captureLatestFrame() for manual capture.
7. Call verifyImage() then acceptImage() on the capture result.
8. Call submitCapture() when all required images have been accepted.
9. Call clearSession() when the flow is complete.

Capture Scope

Use this guide for integrations where your application owns the page shell and embeds the SDK camera in its own UI.

The SDK handles:

• camera initialization and teardown
• frame analysis for auto capture
• post-capture image verification
• accepted-image association with the active transaction

Your application handles:

• the surrounding DOM, controls, and page layout
• browser camera permission prompts
• whether the current step is document or selfie capture
• whether to use auto capture or manual capture
• whether to accept or retake a verified image
• when to submit or clear the session

Package And Compatibility

| Package | Purpose | | --- | --- | | @trulioo/kyc-documents-capture/api | Camera, session, and capture operations | | @trulioo/kyc-documents-capture/docs | Configuration context, consent, metadata, and desktop handoff helpers | | @trulioo/kyc-documents-capture/network | Network state and status subscriptions | | @trulioo/kyc-documents-capture/styles | CSS required when rendering the Capture camera UI |

Installation

Install from npm:

npm install @trulioo/kyc-documents-capture

Use the runtime API from the latest CDN release:

import {
  initializeCapture,
  createCaptureCamera,
  submitCapture,
  clearSession,
} from "https://cdn.trulioo.com/web/sdk/kyc-documents-capture/latest/api.mjs";

Use a pinned CDN version for production:

import {
  initializeCapture,
  createCaptureCamera,
  submitCapture,
  clearSession,
} from "https://cdn.trulioo.com/web/sdk/kyc-documents-capture/VERSION_NUMBER/api.mjs";

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

The same first-party CDN also provides the additional public entrypoints. Replace latest with VERSION_NUMBER when pinning these imports for production:

• https://cdn.trulioo.com/web/sdk/kyc-documents-capture/latest/docs.mjs
• https://cdn.trulioo.com/web/sdk/kyc-documents-capture/latest/network.mjs

Styling

When rendering the Capture camera UI from the npm package, import its stylesheet once from the host application's entry file:

import "@trulioo/kyc-documents-capture/styles";

For a CDN integration, load the stylesheet before the JavaScript module and use the same version as the imported runtime:

<link
  rel="stylesheet"
  href="https://cdn.trulioo.com/web/sdk/kyc-documents-capture/VERSION_NUMBER/main.css"
/>

Before You Start

Before starting a Capture flow, 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 document or selfie capture journey
• has an element available for the camera UI to render into
• handles browser camera permission

Initialization

import {
  initializeCapture,
  createCaptureCamera,
  submitCapture,
  clearSession,
} from "@trulioo/kyc-documents-capture/api";

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

initializeCapture(shortCode)
  .then((transactionId) => {
    console.log("Initialized transaction:", transactionId);

    const camera = createCaptureCamera();

    return camera.render("camera-root").then(() => {
      return camera.startFeedback().then((result) => {
        return result.verifyImage().then((verifyFeedback) => {
          const accepted = verifyFeedback.verifyResponses.some((value) => {
            return value === "SUCCESS" || value === "SUCCESS_REQUIRES_BACK";
          });

          if (!accepted) {
            throw new Error("Captured image was not accepted");
          }

          return result.acceptImage();
        });
      });
    });
  })
  .then(() => submitCapture())
  .then(() => {
    clearSession();
    console.log("Capture flow completed");
  })
  .catch((error) => {
    console.error("Capture flow failed:", error);
  });

What Initialization Does

Call initializeCapture(shortCode) before creating cameras or submitting the transaction. It resolves the active Capture session, authorizes the transaction, fetches configuration, and returns the transaction ID.

import { initializeCapture } from "@trulioo/kyc-documents-capture/api";

const transactionId = await initializeCapture(shortCode);
console.log("Active transaction:", transactionId);

Always initialize with a shortcode created for the active transaction. Do not reuse a stale shortcode across sessions. After calling clearSession(), call initializeCapture() again before reusing the SDK.

Initialization Result

initializeCapture(shortCode) resolves with the active transaction ID. Retain it for host diagnostics and support correlation; the Capture runtime retains the active session internally until clearSession() is called.

Capture Capabilities

Creating And Rendering A Camera

Use createCaptureCamera() to create a camera. Document capture is the default.

import {
  createCaptureCamera,
  DetectionType,
} from "@trulioo/kyc-documents-capture/api";

// Document camera (default)
const documentCamera = createCaptureCamera();

// Selfie camera
const selfieCamera = createCaptureCamera({
  detectionType: DetectionType.BIOMETRIC_SELFIE,
});

Render the camera into an existing DOM element by passing the parent element ID:

const camera = createCaptureCamera();

camera.onFeedbackState((state) => {
  console.log("Feedback state:", state);
});

camera.onCaptureRegion((region) => {
  console.log("Capture region:", region);
});

camera
  .render("parent-element-id", {
    backgroundColor: "#00000050",
  })
  .then(() => {
    console.log("Camera loaded");
  })
  .catch((error) => {
    console.error("Camera failed to load:", error);
  });

After rendering, inspect the active stream resolution:

camera.getResolution().then((resolution) => {
  console.log("Resolution:", resolution.width, resolution.height);
});

Use resume() when the same camera instance should continue preview after an interruption, a paused stream, or image review. Do not create a new camera for that case:

camera.resume();

Use remove() to remove the rendered camera:

camera.remove();

Capturing An Image

Auto Capture

Call startFeedback() to let the SDK process frames until it captures an acceptable image:

camera.startFeedback().then((result) => {
  console.log("Captured image:", result.imageId);
  console.log("Detection type:", result.detectionType);
  console.log("Feedback:", result.imageFeedbacks);
});

Stop an active auto-capture session:

camera.stopFeedback();

If stopFeedback() is called while startFeedback() is in progress, the promise rejects with a stopped-feedback error. Handle this as an expected case rather than a fatal error:

camera.startFeedback().catch((error) => {
  if (error && error.code === 1100) {
    console.log("Feedback stopped intentionally.");
    return;
  }

  console.error("Unexpected feedback error:", error);
});

Apply your own acceptance rule while retaining SDK frame analysis with startFeedbackWithFilter():

camera
  .startFeedbackWithFilter((feedback) => {
    return feedback.imageFeedbacks.includes("SUCCESS");
  })
  .then((result) => {
    console.log("Captured filtered image:", result.imageId);
  });

Manual Capture

Use captureLatestFrame() to trigger manual capture instead of waiting for auto capture:

camera.captureLatestFrame().then((result) => {
  console.log("Manually captured image:", result.imageId);
});

Verifying And Accepting An Image

After capturing an image, call verifyImage() for post-capture feedback. Then call acceptImage() to mark the image as accepted for the transaction.

verifyImage() does not finalize the transaction; it gives your application the information it needs to decide whether to keep or retake the image.

camera.startFeedback().then((result) => {
  result.verifyImage().then((verifyFeedback) => {
    if (!verifyFeedback.isVerifyAttemptAvailable) {
      console.log("No further verify attempts available.");
    }

    console.log("Verify responses:", verifyFeedback.verifyResponses);

    const accepted = verifyFeedback.verifyResponses.some((value) => {
      return value === "SUCCESS" || value === "SUCCESS_REQUIRES_BACK";
    });

    if (accepted) {
      result.acceptImage().then(() => {
        console.log("Image accepted.");
      });
    }
  });
});

Verify attempts are limited. Check isVerifyAttemptAvailable before calling verifyImage() again, and avoid repeated verify calls once it is false.

Recommended acceptance rule: treat SUCCESS and SUCCESS_REQUIRES_BACK as accepted outcomes for image upload.

Resetting State And Submitting The Capture

Call submitCapture() after all required images have been accepted:

await submitCapture();

Then clear the local runtime state:

clearSession();

submitCapture() does not clear local runtime state by itself. Always call clearSession() when the flow is complete or abandoned.

Error Handling

Handle rejected Capture promises before continuing the flow. Do not use cameras or image results after clearSession(); initialize a new Capture session first.

• Initialization errors: initializeCapture(shortCode) rejects when the shortcode is invalid, the active transaction cannot be authorized, or Capture configuration cannot be loaded. Do not create a camera until initialization succeeds.
• Render errors: camera.render(...) rejects when the target element does not exist or the browser cannot provide camera access. Ensure the host element is mounted and handle a denied permission prompt in the surrounding application UI.
• Auto-capture errors: startFeedback() and startFeedbackWithFilter() reject when capture cannot continue. A stopped feedback session is expected: calling stopFeedback() during auto capture rejects the pending call with error code 1100.
• Manual-capture, verify, and accept errors: captureLatestFrame(), verifyImage(), and acceptImage() reject when the current camera or image is no longer valid, or when the Capture service cannot complete the operation. Keep the camera and returned image result within the active session.
• Submission errors: submitCapture() rejects when the transaction is not ready for submission or the service cannot finalize it. Verify and accept every required image before submitting.
• Session reset: clearSession() clears the local Capture runtime. Discard the previous camera and image-result references, then call initializeCapture() with a new active shortcode before reuse.

Troubleshooting

• Initialization fails: confirm the shortcode is valid and belongs to the expected environment.
• Camera UI does not appear: confirm the parent DOM element exists and browser camera permission has been granted.
• Auto capture never completes: use onFeedbackState() to determine whether the SDK is repeatedly requesting a retake condition. This usually indicates a lighting or framing issue.
• Verify or accept fails: confirm the image came from the current active session and was not invalidated by an earlier clearSession() call.