> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compliance.legaltalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Trigger Monitoring

> Trigger an immediate screening check on all subjects in a watchlist

## Endpoint

```
POST /kyc/watchlists/{watchlist_id}/monitor
```

## Overview

Manually trigger the screening process for a specific watchlist. This executes the ongoing monitoring check immediately instead of waiting for the next scheduled check, returning the results synchronously.

<Info>
  This is useful for:

  * Immediate screening after adding new subjects
  * On-demand compliance checks
  * Testing watchlist configuration before going live
</Info>

## Authentication

Requires `watchlist:update` permission.

## Path Parameters

<ParamField path="watchlist_id" type="string" required>
  The unique identifier of the watchlist to monitor
</ParamField>

## Request Example

```bash theme={null}
curl -X POST https://stg.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/monitor \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Response

### Success Response (200 OK)

```json theme={null}
{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "watchlist_name": "High Risk Customers",
    "subjects_checked": 5,
    "total_matches": 2,
    "previous_matches": 1,
    "new_matches_count": 1,
    "has_changes": true,
    "results_by_list": {
      "ofac": {
        "checked": 5,
        "matches": 1
      },
      "un": {
        "checked": 5,
        "matches": 1
      }
    },
    "duration_ms": 1250,
    "checked_at": "2024-11-22T14:30:00Z"
  },
  "execution_context": {
    "timestamp": "2024-11-22T14:30:01Z",
    "request_id": "abc123..."
  }
}
```

## Response Fields

| Field               | Type    | Description                             |
| ------------------- | ------- | --------------------------------------- |
| `watchlist_id`      | string  | The watchlist that was checked          |
| `watchlist_name`    | string  | Name of the watchlist                   |
| `subjects_checked`  | integer | Number of subjects screened             |
| `total_matches`     | integer | Total matches found in current check    |
| `previous_matches`  | integer | Matches from previous check             |
| `new_matches_count` | integer | New matches since last check            |
| `has_changes`       | boolean | Whether any match status changed        |
| `results_by_list`   | object  | Breakdown of results per sanctions list |
| `duration_ms`       | integer | Check duration in milliseconds          |
| `checked_at`        | string  | Timestamp of the check (ISO 8601)       |

## Error Responses

### 400 Bad Request - Watchlist Not Active

```json theme={null}
{
  "status": "error",
  "error": "Watchlist must be active to trigger monitoring. Current status: paused"
}
```

The watchlist is paused. [Update the status](/api-reference/watchlists/update) to `active` first.

### 400 Bad Request - No Subjects

```json theme={null}
{
  "status": "error",
  "error": "Watchlist has no subjects to monitor"
}
```

The watchlist has no subjects. [Add subjects](/api-reference/watchlists/add-subjects) before triggering monitoring.

### 404 Not Found

```json theme={null}
{
  "status": "error",
  "error": "Watchlist not found"
}
```

## Usage Examples

### Python

```python theme={null}
import requests

watchlist_id = "550e8400-e29b-41d4-a716-446655440000"
url = f"https://stg.kyc.legaltalent.ai/kyc/watchlists/{watchlist_id}/monitor"

headers = {
    "Authorization": "Bearer YOUR_TOKEN"
}

response = requests.post(url, headers=headers)
result = response.json()

if result["status"] == "success":
    data = result["data"]
    print(f"Checked {data['subjects_checked']} subjects")
    print(f"Found {data['new_matches_count']} new matches")
    
    if data["has_changes"]:
        print("⚠️ Match status changed since last check!")
        for list_name, stats in data["results_by_list"].items():
            print(f"  {list_name}: {stats['matches']} matches")
```

### JavaScript

```javascript theme={null}
const watchlistId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://stg.kyc.legaltalent.ai/kyc/watchlists/${watchlistId}/monitor`;

fetch(url, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
  .then(response => response.json())
  .then(result => {
    if (result.status === 'success') {
      const { subjects_checked, new_matches_count, has_changes } = result.data;
      console.log(`Checked ${subjects_checked} subjects`);
      console.log(`Found ${new_matches_count} new matches`);
      
      if (has_changes) {
        console.log('⚠️ Match status changed!');
      }
    }
  });
```

## Status Codes

| Code | Description                                           |
| ---- | ----------------------------------------------------- |
| 200  | Success - Monitoring completed                        |
| 400  | Bad Request - Watchlist not active or has no subjects |
| 401  | Unauthorized - Missing or invalid token               |
| 403  | Forbidden - Missing `watchlist:update` permission     |
| 404  | Not Found - Watchlist not found                       |
| 500  | Internal Server Error                                 |

## Best Practices

<AccordionGroup>
  <Accordion title="Use for On-Demand Checks">
    For watchlists with `check_frequency: "on_update"`, use this endpoint to trigger manual checks whenever needed instead of relying on scheduled checks.
  </Accordion>

  <Accordion title="Check After Adding Subjects">
    When adding subjects to an active watchlist, consider triggering an immediate check to get screening results without waiting for the next scheduled run.
  </Accordion>

  <Accordion title="Monitor has_changes Flag">
    The `has_changes` field indicates whether any subjects gained or lost matches since the last check. Use this to trigger downstream processes only when needed.
  </Accordion>

  <Accordion title="Review results_by_list">
    The breakdown by list helps identify which sanctions lists are triggering matches, useful for risk assessment and compliance reporting.
  </Accordion>
</AccordionGroup>

## Rate Limiting

Monitoring operations are resource-intensive. Avoid triggering monitoring too frequently:

* For `daily` watchlists, limit to 1-2 manual triggers per day
* For large watchlists (100+ subjects), allow 5-10 minutes between triggers

## Next Steps

* [View screening results](/api-reference/watchlists/get) in watchlist details
* [Configure alerts](/api-reference/watchlists/update) for automatic notifications
* Track usage with the [Usage API](/api-reference/usage)