---
updatedAt: 2026-08-20T21:56:02.000Z
agentTools:
  projectIndex: https://developer.trulioo.com/llms.txt
---

# Trulioo KYC Documents Capture SDK - Web Guide

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                                |
| `@trulioo/kyc-documents-capture/styles`  | CSS required when rendering the Capture camera UI                     |

## Installation

Install from npm:

```bash
npm install @trulioo/kyc-documents-capture
```

Use the runtime API from the latest CDN release:

```javascript
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:

```javascript
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:

```javascript
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:

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

## End-To-End Example

```javascript
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.

```javascript
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.

```javascript
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:

```javascript
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:

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

Tear down or resume the camera as needed:

```javascript
camera.remove();
camera.resume();
```

## Capturing An Image

### Auto Capture

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

```javascript
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:

```javascript
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:

```javascript
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()`:

```javascript
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:

```javascript
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.

```javascript
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:

```javascript
await submitCapture();
```

Then clear the local runtime state:

```javascript
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:

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

Use the `network` entrypoint to react to connectivity changes:

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