# Custom Watchlist Module

<WebSDK2 />

The Custom Watchlist module screens the user's face against a customer-provided blocklist. Fire-and-forget — runs server-side using images already in the session.

> Follows the [backend-process pattern](doc:web-sdk-2-module-patterns#3-backend-process-modules). See the patterns page for the shared lifecycle.

## Availability

This module is headless-only — there is no public `<incode-custom-watchlist>` web component. Drive it with `createCustomWatchlistManager` from `@incodetech/core/custom-watchlist`. Typically invoked from an orchestrated flow.

## Configuration

```typescript
type CustomWatchlistConfig = {
  failIfFaceOnBlocklist: boolean;
  addSuspectedFraudAutomatically: boolean;
  autoExecution: boolean;
};
```

| Option                           | Type      | Required | Description                                                                                  |
| -------------------------------- | --------- | -------- | -------------------------------------------------------------------------------------------- |
| `failIfFaceOnBlocklist`          | `boolean` | ✅        | Server-side behavior: mark the verification as failed if the face matches a blocklist entry. |
| `addSuspectedFraudAutomatically` | `boolean` | ✅        | Add the user to a suspected-fraud list automatically on a match.                             |
| `autoExecution`                  | `boolean` | ✅        | Auto-execute the check (vs. requiring an explicit trigger).                                  |

These fields are supplied by the backend flow configuration and shape backend behavior. The module itself is fire-and-forget from the client's perspective — the client doesn't need to read these values to drive its own UI.

## State machine

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

| Status       | Description                    |
| ------------ | ------------------------------ |
| `idle`       | Initial state.                 |
| `processing` | Backend screening in progress. |
| `success`    | Screening completed.           |
| `finished`   | Terminal.                      |

## See also

* [Module: Watchlist](doc:web-sdk-2-module-watchlist) — global sanctions / PEP screening
* [Module Patterns → backend-process](doc:web-sdk-2-module-patterns#3-backend-process-modules)
* [Individual Modules](doc:web-sdk-2-individual-modules)