Trigger Monitoring

curl --request POST \
  --url https://api.example.com/kyc/watchlists/{watchlist_id}/monitor

const options = {method: 'POST'};

fetch('https://api.example.com/kyc/watchlists/{watchlist_id}/monitor', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/kyc/watchlists/{watchlist_id}/monitor",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/kyc/watchlists/{watchlist_id}/monitor"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/kyc/watchlists/{watchlist_id}/monitor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

kyc

watchlists

{watchlist_id}

monitor

Trigger Monitoring

curl --request POST \
  --url https://api.example.com/kyc/watchlists/{watchlist_id}/monitor

const options = {method: 'POST'};

fetch('https://api.example.com/kyc/watchlists/{watchlist_id}/monitor', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/kyc/watchlists/{watchlist_id}/monitor",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/kyc/watchlists/{watchlist_id}/monitor"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/kyc/watchlists/{watchlist_id}/monitor")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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

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

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

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

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

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.

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.

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.

Review results_by_list

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

View screening results in watchlist details
Configure alerts for automatic notifications
Track usage with the Usage API

Overview

Compliance Screening

AI Analysis

Batch Processing

KYC Workflows & Sessions

Webhooks

Tenant Management

Watchlists

Reporting & Analytics

Monitoring

Trigger Monitoring

Endpoint

Overview

Authentication

Path Parameters

Request Example

Response

Success Response (200 OK)

Response Fields

Error Responses

400 Bad Request - Watchlist Not Active

400 Bad Request - No Subjects

404 Not Found

Usage Examples

Python

JavaScript

Status Codes

Best Practices

Rate Limiting

Next Steps

​Endpoint

​Overview

​Authentication

​Path Parameters

​Request Example

​Response

​Success Response (200 OK)

​Response Fields

​Error Responses

​400 Bad Request - Watchlist Not Active

​400 Bad Request - No Subjects

​404 Not Found

​Usage Examples

​Python

​JavaScript

​Status Codes

​Best Practices

​Rate Limiting

​Next Steps

Endpoint

Overview

Authentication

Path Parameters

Request Example

Response

Success Response (200 OK)

Response Fields

Error Responses

400 Bad Request - Watchlist Not Active

400 Bad Request - No Subjects

404 Not Found

Usage Examples

Python

JavaScript

Status Codes

Best Practices

Rate Limiting

Next Steps