---
title: "Custom Watchlist Module"
url: "https://developer.incode.com/sdk-reference/web-sdk-2-module-custom-watchlist/"
section: "sdk-reference"
group: "Incode Web SDK 2 Reference / Web SDK 2 Individual Modules"
version: "v1.1"
status: "live"
---
# Custom Watchlist 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. <br /><br />Full rollout to all clients still TBD.
:::

<br />

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](/sdk-reference/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](/sdk-reference/web-sdk-2-module-watchlist/) — global sanctions / PEP screening
- [Module Patterns → backend-process](/sdk-reference/web-sdk-2-module-patterns/#3-backend-process-modules)
- [Individual Modules](/sdk-reference/web-sdk-2-individual-modules/)