📘

This guide is specific to Web SDK 2.0. If you are still using 1.x, you can find documentation [here](https://developer.incode.com/docs/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 Document Upload module is a file-picker-only upload path for documents — used when live camera capture isn't appropriate (e.g., a third ID document, or a document the user has stored as a PDF). Unlike [Document Capture](https://developer.incode.com/docs/web-sdk-2-module-document-capture), it does not offer a camera mode.

Follows a slim variant of the [camera-capture pattern](https://developer.incode.com/docs/web-sdk-2-module-patterns#2-camera-capture-modules) — initialize → capture (file pick) → upload → finished. No tutorial, no permissions, no live ML detection. See the patterns page for the shared lifecycle.

## Availability

This module is headless-only — there is no public `<incode-document-upload>` web component. Drive it with `createDocumentUploadManager` from `@incodetech/core/document-upload` and render your own file-picker UI.

## Configuration

TypeScript

```typescript
type DocumentUploadConfig = {
  documentType: string; // Required. Sent to the upload endpoint as a query parameter (e.g., 'thirdId').
};
```

| Option          | Type    | Required | Description                                           |
|-----------------|---------|----------|-------------------------------------------------------|
| `documentType`  | `string`| ✅       | Document-type identifier the upload endpoint expects. Common value: `'thirdId'`. |

## State machine

`DocumentUploadState` is a discriminated union over `status`:

| Status       | Description                                            |
|--------------|--------------------------------------------------------|
| `initializing` | Setting up; brief.                                    |
| `capturing`  | Waiting for the user to pick a file.                  |
| `uploading`  | File picked; uploading to the backend with progress.   |
| `finished`   | Terminal — module complete.                             |
| `closed`     | User dismissed.                                         |
| `error`      | Fatal error. Inspect `state.error` for the error code. |

Error codes (`DOCUMENT_UPLOAD_ERROR_CODES`):

- `DOCUMENT_UPLOAD_ERROR` — upload itself failed
- `DOCUMENT_UPLOAD_CAMERA_ERROR` — legacy code, kept for backward compatibility

## API methods

| Method                | Purpose                                          |
|-----------------------|--------------------------------------------------|
| `start()`             | Open the file picker (transitions from `initializing`).|
| `capture(imageBase64)`| Provide the picked file's data.                  |
| `retry()`            | After `error`, retry the upload.                 |
| `close()`            | Dismiss (transitions to `closed`).                |

Plus the universal lifecycle: `subscribe`, `getState`, `reset`, `stop`.