# Document Upload Module

<WebSDK2 />

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](doc:web-sdk-2-module-document-capture), it does not offer a camera mode.

> Follows a slim variant of the [camera-capture pattern](doc: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
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`.

## See also

* [Module: Document Capture](doc:web-sdk-2-module-document-capture): full camera + file capture variant
* [Module Patterns → camera-capture](doc:web-sdk-2-module-patterns#2-camera-capture-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)