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 Start

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.

What This SDK Covers

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 Entrypoints

| 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 |

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

End-To-End Example

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);
  });

Initialization

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.

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);
});

Tear down or resume the camera as needed:

camera.remove();
camera.resume();

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.

Submitting And Clearing The Session

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.

Docs And Network Helpers

Use the docs entrypoint for configuration context, consent, metadata, and desktop-to-mobile handoff:

import {
  getConfigurationContext,
  recordConsent,
  sendMetadata,
} from "@trulioo/kyc-documents-capture/docs";

Use the network entrypoint to react to connectivity changes:

import {
  getNetworkStatus,
  observeNetworkStatus,
} from "@trulioo/kyc-documents-capture/network";

console.log(getNetworkStatus());

const subscription = observeNetworkStatus({
  onChange(status) {
    console.log("Network status changed:", status);
  },
});

subscription.cancel();

Result Reference

| Method | Returns | Key fields | | --- | --- | --- | | startFeedback() | CaptureImageResult | imageId, detectionType, imageFeedbacks | | startFeedbackWithFilter() | CaptureImageResult | imageId, detectionType, imageFeedbacks | | captureLatestFrame() | CaptureResult | imageId | | verifyImage() | CaptureVerifyFeedback | isVerifyAttemptAvailable, verifyResponses |

Public API Reference

• Session and submission: initializeCapture(shortCode), submitCapture(), clearSession()
• Camera creation: createCaptureCamera(config?), DetectionType
• Camera operations: render(parentElementId, props?), startFeedback(), startFeedbackWithFilter(filter), captureLatestFrame(), stopFeedback(), onFeedbackState(callback), onCaptureRegion(callback), getResolution(), resume(), remove()
• Capture result operations: verifyImage(), acceptImage()

Common Mistakes

• Calling createCaptureCamera() before initializeCapture() completes. Initialization must succeed before creating or rendering a camera.
• Rendering into a DOM element that does not exist yet. Confirm the parent element is present before calling render(...).
• Calling submitCapture() before all required images are accepted. Verify and accept each required image before submitting.
• Assuming submitCapture() also clears local state. Always call clearSession() after submitting or abandoning a flow.
• Treating a stopped feedback session as a fatal error. A stopFeedback() call during auto capture rejects startFeedback() with error code 1100; handle it as an intentional stop.

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.

Diagnostic Checklist

When filing a support issue, include:

• [ ] Capture SDK version
• [ ] Browser name and version
• [ ] Operating system and device type
• [ ] Whether the flow was document or selfie capture
• [ ] Whether the issue occurred during auto capture or manual capture
• [ ] Transaction ID, if available
• [ ] Latest feedback state or verify responses
• [ ] Failing stage: initialize, render, capture, verify, accept, or submit