# Identity Reuse Module

<WebSDK2 />

The Identity Reuse module recognizes a returning user by matching their selfie against existing on-file biometric records, then offering them the choice to reuse the existing identity (skipping fresh ID + selfie capture) or proceed with a new verification.

> Follows the [form-based pattern](doc:web-sdk-2-module-patterns#1-form-based-modules) with selection sub-states. The user reviews candidate matches and submits their choice. See the patterns page for the shared lifecycle.

## Tag

`<incode-identity-reuse>` 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/identity-reuse';
import '@incodetech/web/identity-reuse/styles.css';
```

## Properties

| Property   | Type                      | Required | Description                                |
| ---------- | ------------------------- | -------- | ------------------------------------------ |
| `config`   | `IdentityReuseConfig`     | ❌        | No options                                 |
| `onFinish` | `() => void`              | ❌        | Called when the user's choice is submitted |
| `onError`  | `(error: string) => void` | ❌        | Called when an error occurs                |

## Configuration

The module takes no configuration:

```typescript
type IdentityReuseConfig = {};
```

Candidate sources (which prior identities are considered) are configured server-side.

## State machine

`IdentityReuseState` is a discriminated union over `status`. The selection states (`oneCandidateFound`, `multiCandidatesFound`, `noCandidatesFound`) are unique to this module:

| Status                 | Description                                             |
| ---------------------- | ------------------------------------------------------- |
| `idle`                 | Initial state.                                          |
| `loading`              | Fetching candidate matches from the backend.            |
| `oneCandidateFound`    | Single match found. User confirms or rejects.           |
| `multiCandidatesFound` | Multiple matches; user picks one (or skips).            |
| `noCandidatesFound`    | No matches; user proceeds with a fresh verification.    |
| `submitContinue`       | User chose to reuse a candidate; submitting the choice. |
| `submitSkip`           | User chose to skip reuse; submitting the skip.          |
| `finished`             | Terminal.                                               |
| `error`                | Fatal error.                                            |

The candidate states expose `currentOrganizationName` and `candidateOrganizationNames` from the backend response.

## API methods

| Method                              | Purpose                                                     |
| ----------------------------------- | ----------------------------------------------------------- |
| `load()`                            | Fetch candidate matches.                                    |
| `startSelection()`                  | Begin selecting from `multiCandidatesFound`.                |
| `chooseCandidate(organizationName)` | Pick a candidate by organization name.                      |
| `changeCandidate()`                 | Go back to selection from `submitContinue` (before submit). |
| `submitCandidate()`                 | Submit the chosen candidate (reuse).                        |
| `skip()`                            | Skip reuse and proceed with fresh verification.             |
| `retry()`                           | After `error`, restart.                                     |

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

## See also

* [Module: Selfie](doc:web-sdk-2-module-selfie-1): fallback when reuse is skipped or no candidates found
* [Module: Authentication](doc:web-sdk-2-module-authentication): different re-auth flow (selfie ↔ stored biometric)
* [Module Patterns → form-based](doc:web-sdk-2-module-patterns#1-form-based-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)