# Custom Watchlist

The Custom Watchlist module screens the user's collected data, including biometric face data when available, against your organization's private watchlist of blocked or trusted users, and influences the Session outcome accordingly. It runs as a background process and isn't visible to the end user. The lists and matching criteria are driven by your Incode configuration.

For an overview of this module and how it works, see [Custom Watchlist](https://developer.incode.com/docs/custom-watchlist).

How you use this module depends on your [integration pattern](https://developer.incode.com/docs/android-common-implementation-patterns#integration-patterns). In Patterns 1 and 2, you add the module to a `FlowConfig` in code as shown on this page. In Pattern 3, you define your modules and configuration in Dashboard as a Flow or Workflow and reference it by ID with `startFlow()` or `startWorkflow()` as shown on [Run Flows Configured in Dashboard](https://developer.incode.com/docs/android-run-flows-configured-online).

## Add Custom Watchlist

Add the module with `addCustomWatchlist()`. If you also use the [Antifraud](https://developer.incode.com/docs/android-antifraud) module, call `addAntifraud()` first, then `addCustomWatchlist()`, so Custom Watchlist runs after Antifraud. 

```kotlin
flowConfigBuilder.addCustomWatchlist()
```
```java
flowConfigBuilder.addCustomWatchlist();
```

Custom Watchlist ships both a v1 (legacy View) and a v2 (Jetpack Compose) capture screen; the active one depends on your Incode configuration. Contact your Incode representative to enable v2.

### Example

The example below adds Custom Watchlist as the only step in the flow and listens for the result through `onCustomWatchlistProcessed()`.

```kotlin
val flowConfig = FlowConfig.Builder()
    .addCustomWatchlist()
    .build()

val onboardingListener = object : OnboardingListener() {
    override fun onCustomWatchlistProcessed(customWatchlistResult: CustomWatchlistResult) {
        // Custom watchlist step processed. Inspect the result.
    }
}

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener)
```
```java
FlowConfig flowConfig = new FlowConfig.Builder()
    .addCustomWatchlist()
    .build();

IncodeWelcome.OnboardingListener onboardingListener = new IncodeWelcome.OnboardingListener() {
    @Override
    public void onCustomWatchlistProcessed(@NonNull CustomWatchlistResult customWatchlistResult) {
        // Custom watchlist step processed. Inspect the result.
    }
};

IncodeWelcome.getInstance()
    .startOnboarding(activityContext, sessionConfig, flowConfig, onboardingListener);
```

## Configuration Options

Custom Watchlist has no configurable options. It is added with a no-argument builder method. The watchlist sources and matching behavior are controlled by your Incode Flow or Workflow configuration.

For the complete option set, see `CustomWatchlist` in [API Reference](https://developer.incode.com/docs/android-api-reference).

## Result

Custom Watchlist delivers a `CustomWatchlistResult` to the `onCustomWatchlistProcessed(CustomWatchlistResult)` callback on your `IncodeWelcome.OnboardingListener`. Key fields include:

- `success`: `true` if the custom watchlist check completed successfully; otherwise, `false`.
- Fields inherited from `BaseResult`:
  - `resultCode`: The `ResultCode` for this result.
  - `error`: When `resultCode` is `ERROR`, the `Throwable` that caused it; otherwise, `null`.
  - `deviceStats`: The `DeviceStats` snapshot of the device state when the result was produced.
  - `motionStatus`: Device motion assessment during capture. One of the following:
    - `UNCLEAR`: Motion could not be determined; the default.
    - `PASS`: Device motion was within acceptable limits.
    - `FAIL`: Excessive device motion was detected.

Errors surface via `OnboardingListener.onError(Throwable)`. This module does not define a module-specific exception type.

For all fields, see `CustomWatchlistResult` in [API Reference](https://developer.incode.com/docs/android-api-reference).