---
title: "ID Capture Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-id-capture/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# ID Capture Module
:::note
This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](/sdk-reference/web-sdk-reference). Contact your Incode Representative for upgrade information and check if you are a candidate for this upgrade.
Full rollout to all clients still TBD.
:::
The ID Capture module captures front and back images of identity documents (ID cards, passports) with ML-powered quality checks and validation.
> Follows the [camera-capture pattern](/sdk-reference/web-sdk-2-module-patterns/#2-camera-capture-modules), plus dedicated states for mandatory consent and manual file upload. See the patterns page for the shared lifecycle; the rest of this page covers ID-specific config, capture properties, and methods.
## Tag
`` is a standard Web Component. Importing the UI subpath registers the custom element; importing the CSS applies the module's styles.
```ts
import '@incodetech/web/id';
import '@incodetech/web/id/styles.css';
```
## Properties
Set these as JavaScript properties on the element (not as HTML attributes):
| Property | Type | Required | Description |
| ---------- | -------------------------------------- | -------- | ------------------------------------------ |
| `config` | `IdCaptureConfig` | ❌ | Configuration for ID capture behavior |
| `manager` | `IdCaptureManager` | ❌ | Optional pre-built manager (advanced use) |
| `onFinish` | `() => void` | ❌ | Called when capture completes successfully |
| `onError` | `(error: string \| undefined) => void` | ❌ | Called when an error occurs |
## WASM Requirements
The ID Capture module uses WebAssembly for document detection, blur/glare quality checks, and perspective correction. Pre-warm WASM during `setup()` so models are ready before the user reaches the camera step:
```typescript
await setup({
apiURL: 'https://demo-api.incodesmile.com',
token: 'your-session-token',
wasm: { pipelines: ['idCapture'] },
});
```
See [WASM Configuration](/sdk-reference/web-sdk-2-wasm/) for self-hosted paths and the lower-level `warmupWasm()` API.
## Usage
### Vanilla HTML / TypeScript
```html
```
### React
> **React 18 or earlier:** add the one-time JSX augmentation from [Framework Integration → TypeScript: JSX support for `incode-*` tags](/sdk-reference/web-sdk-2-framework-integration/#typescript-jsx-support-for-incode--tags). React 19+ doesn't need it, and can also use the simpler form from [Framework Integration → React 19+ shortcut](/sdk-reference/web-sdk-2-framework-integration/#react-19-shortcut).
```tsx
import { useEffect, useRef } from 'react';
import { setup } from '@incodetech/core';
import type { IdCaptureConfig } from '@incodetech/core/id';
import '@incodetech/web/id';
import '@incodetech/web/id/styles.css';
type IdElement = HTMLElement & {
config: IdCaptureConfig;
onFinish: () => void;
onError: (error: string | undefined) => void;
};
await setup({
apiURL: 'https://demo-api.incodesmile.com',
token: 'your-session-token',
wasm: { pipelines: ['idCapture'] },
});
export function IdCapture() {
const ref = useRef(null);
useEffect(() => {
const el = ref.current;
if (!el) return;
el.config = {
showTutorial: true,
enableId: true,
enablePassport: false,
autoCaptureTimeout: 5,
captureAttempts: 3,
};
el.onFinish = () => console.log('ID captured!');
el.onError = (err) => console.error('ID error:', err);
}, []);
return ;
}
```
For Angular (`CUSTOM_ELEMENTS_SCHEMA`) and Vue (`compilerOptions.isCustomElement`) setup, see [Framework Integration](/sdk-reference/web-sdk-2-framework-integration/).
---
## Workflow vs Flow
In a dashboard-driven Flow (`` / `createOrchestratedFlowManager`), `ID` is a single step that captures the document **and** runs server-side processing (`/process/id`). This is what `` and `createIdCaptureManager` do by default.
In a server-driven Workflow (`` / `createWorkflowManager`), the workflow engine emits ID handling as **two distinct nodes**:
1. `ID_CAPTURE` — runs `idCaptureMachine` for the capture portion only, then advances without calling `/process/id`. Enabled by setting `IdCaptureConfig.skipProcessId = true` (the workflow engine sets this automatically on the `ID_CAPTURE` node's config).
2. `ID` — runs the headless `id-verification` module (`@incodetech/core/id-verification`, `createIdVerificationManager`) which invokes `/process/id` on its own. The orchestrator renders the corresponding `` shell while the request is in flight. No UI work needed.
This split lets the workflow inject custom logic (manual review, retries, branching) between capture and verification. For a single-step capture+verify flow, keep using the standard `` / `createIdCaptureManager` path — `skipProcessId` defaults to `false`, so processing runs inline as before.
The `id-verification` module ships:
- `createIdVerificationManager` from `@incodetech/core/id-verification`: headless manager for the verification half (used by Workflow's `ID` node, also usable headlessly outside Workflow).
- `IdVerificationConfig`: config type for the manager.
- ``: Preact UI shell registered automatically by the orchestrator; no public `@incodetech/web/id-verification` import path, since the orchestrator owns the mount.
---
## Headless Mode
For complete UI control, use the `createIdCaptureManager` from `@incodetech/core/id`.
### Quick Start
```tsx
import { setup } from '@incodetech/core';
import { createIdCaptureManager } from '@incodetech/core/id';
import { warmupWasm } from '@incodetech/core/wasm';
await setup({
apiURL: 'https://demo-api.incodesmile.com',
token: 'your-session-token',
});
await warmupWasm({
wasmPath: '/wasm/webLib.wasm',
glueCodePath: '/wasm/webLib.js',
modelsBasePath: '/wasm/models',
pipelines: ['idCapture'],
});
const manager = createIdCaptureManager({
config: {
showTutorial: true,
enableId: true,
enablePassport: false,
autoCaptureTimeout: 5,
captureAttempts: 3,
},
});
manager.subscribe((state) => {
console.log('Status:', state.status);
if (state.status === 'capture') {
console.log('Mode:', state.currentMode); // 'front' or 'back'
console.log('Detection:', state.detectionStatus);
console.log('Counter:', state.counterValue); // Auto-capture countdown
}
if (state.status === 'finished') {
console.log('ID captured successfully!');
manager.stop();
}
});
manager.load();
```
### State Machine Flow
```mermaid
flowchart LR
idle -->|load| chooser
chooser -->|selectDocument| tutorial
tutorial -->|nextStep| permissions
permissions -->|granted| capture
capture -->|front done| frontFinished
frontFinished --> capture
capture -->|back done| processing
processing --> finished
```
### States Reference
| Status | Description | Key Properties |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `idle` | Initial state, waiting for `load()` | – |
| `chooser` | Document type selection | `availableDocumentTypes` |
| `loading` | Loading configuration | – |
| `tutorial` | Showing tutorial | `selectedDocumentType`, `currentMode` |
| `ageVerification` | Regulation-required age-confirmation gate before capture. Reached when `config.ageAssurance === true`. Advance with `nextStep()`. | – |
| `permissions` | Camera permission handling | `permissionStatus` |
| `capture` | Active document capture | `stream`, `currentMode`, `detectionStatus`, `counterValue`, `attemptsRemaining` |
| `frontFinished` | Front side complete, transitioning to back | – |
| `backFinished` | Back side complete | – |
| `mandatoryConsent` | Regulation-required consent screen | `regulationType` (see [Mandatory Consent](#mandatory-consent-state-properties)) |
| `processing` | Server-side document processing | – |
| `expired` | Document expired after processing | – |
| `manualUpload` | Manual file upload flow (see [Manual Upload](#manual-upload-state-properties)) | full shape below |
| `digitalIdUpload` | Digital ID upload sub-flow — PDF e-IDs uploaded by file picker (see [Digital ID Upload](#digital-id-upload-state-properties)) | full shape below |
| `finished` | Capture complete | – |
| `error` | Fatal error occurred | `error` |
| `closed` | User closed the flow | – |
### Capture State Properties
When `status === 'capture'`:
| Property | Type | Description |
| -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stream` | `MediaStream` | Camera stream for `