Skip to main content
POST
/
kyc
/
watchlists
/
{watchlist_id}
/
monitor
Trigger Monitoring
curl --request POST \
  --url https://api.example.com/kyc/watchlists/{watchlist_id}/monitor

​
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.
This is useful for:
  • Immediate screening after adding new subjects
  • On-demand compliance checks
  • Testing watchlist configuration before going live

​
Authentication

Requires watchlist:update permission.

​
Path Parameters

​
watchlist_id
string
required
The unique identifier of the watchlist to monitor

​
Request Example

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)

{
  "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

FieldTypeDescription
watchlist_idstringThe watchlist that was checked
watchlist_namestringName of the watchlist
subjects_checkedintegerNumber of subjects screened
total_matchesintegerTotal matches found in current check
previous_matchesintegerMatches from previous check
new_matches_countintegerNew matches since last check
has_changesbooleanWhether any match status changed
results_by_listobjectBreakdown of results per sanctions list
duration_msintegerCheck duration in milliseconds
checked_atstringTimestamp of the check (ISO 8601)

​
Error Responses

​
400 Bad Request - Watchlist Not Active

{
  "status": "error",
  "error": "Watchlist must be active to trigger monitoring. Current status: paused"
}
The watchlist is paused. Update the status to active first.

​
400 Bad Request - No Subjects

{
  "status": "error",
  "error": "Watchlist has no subjects to monitor"
}
The watchlist has no subjects. Add subjects before triggering monitoring.

​
404 Not Found

{
  "status": "error",
  "error": "Watchlist not found"
}

​
Usage Examples

​
Python

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

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

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

​
Best Practices

For watchlists with check_frequency: "on_update", use this endpoint to trigger manual checks whenever needed instead of relying on scheduled checks.
When adding subjects to an active watchlist, consider triggering an immediate check to get screening results without waiting for the next scheduled run.
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.
The breakdown by list helps identify which sanctions lists are triggering matches, useful for risk assessment and compliance reporting.

​
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