Skip to main content
GET
/
kyc
/
watchlists
curl -X POST https://dev.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Risk Customers",
    "subjects": [
      {
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document"
      },
      {
        "full_name": "Jane Smith",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet"
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true,
      "webhook_url": "https://your-server.com/webhooks/kyc",
      "notification_email": "alerts@example.com"
    },
    "status": "active"
  }'

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant123",
    "name": "High Risk Customers",
    "subjects": [
      {
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "added_at": "2024-11-22T10:30:00Z"
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "last_checked_at": null,
    "next_check_due": 1732278600000,
    "last_results": null,
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true,
      "webhook_url": "https://your-server.com/webhooks/kyc",
      "notification_email": "alerts@example.com"
    },
    "status": "active",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}
Manage watchlists for ongoing monitoring of entities against KYC watchlists. Watchlists automatically check subjects at configured intervals and alert on matches or status changes.

​
Overview

Watchlists allow you to:
  • Monitor multiple entities continuously
  • Receive alerts when matches are found
  • Track changes in entity status over time
  • Schedule automatic checks (daily, weekly, or on update)

​
Endpoints

MethodEndpointPermission Required
POST/kyc/watchlistswatchlist:create
GET/kyc/watchlistswatchlist:list
GET/kyc/watchlists/{watchlist_id}watchlist:read
PATCH/kyc/watchlists/{watchlist_id}watchlist:update
DELETE/kyc/watchlists/{watchlist_id}watchlist:delete
POST/kyc/watchlists/{watchlist_id}/subjectswatchlist:update
POST/kyc/watchlists/{watchlist_id}/subjects/batchwatchlist:update
DELETE/kyc/watchlists/{watchlist_id}/subjects/{subject_id}watchlist:update

​
Create Watchlist

Create a new watchlist with subjects to monitor.

​
Request

curl -X POST https://dev.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Risk Customers",
    "subjects": [
      {
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document"
      },
      {
        "full_name": "Jane Smith",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet"
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true,
      "webhook_url": "https://your-server.com/webhooks/kyc",
      "notification_email": "alerts@example.com"
    },
    "status": "active"
  }'

​
Request Parameters

​
Response

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant123",
    "name": "High Risk Customers",
    "subjects": [
      {
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "added_at": "2024-11-22T10:30:00Z"
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "last_checked_at": null,
    "next_check_due": 1732278600000,
    "last_results": null,
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true,
      "webhook_url": "https://your-server.com/webhooks/kyc",
      "notification_email": "alerts@example.com"
    },
    "status": "active",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}

​
List Watchlists

Retrieve all watchlists for your tenant.

​
Request

curl -X GET https://dev.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

{
  "status": "success",
  "data": [
    {
      "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "High Risk Customers",
      "status": "active",
      "subjects_count": 5,
      "last_checked_at": "2024-11-22T09:00:00Z",
      "next_check_due": 1732278600000,
      "check_frequency": "daily"
    },
    {
      "watchlist_id": "660e8400-e29b-41d4-a716-446655440002",
      "name": "Vendor Watchlist",
      "status": "paused",
      "subjects_count": 12,
      "last_checked_at": null,
      "next_check_due": null,
      "check_frequency": "weekly"
    }
  ]
}

​
Get Watchlist Details

Retrieve detailed information about a specific watchlist.

​
Request

curl -X GET https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant123",
    "name": "High Risk Customers",
    "subjects": [
      {
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "added_at": "2024-11-22T10:30:00Z"
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "last_checked_at": "2024-11-22T09:00:00Z",
    "next_check_due": 1732278600000,
    "last_results": {
      "checked_at": "2024-11-22T09:00:00Z",
      "subjects_checked": 5,
      "matches_found": 0,
      "new_matches": 0,
      "s3_snapshot_key": "snapshots/tenant123/550e8400/2024-11-22T09:00:00Z.json"
    },
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true,
      "webhook_url": "https://your-server.com/webhooks/kyc",
      "notification_email": "alerts@example.com"
    },
    "status": "active",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}

​
Update Watchlist

Update watchlist configuration.

​
Request

curl -X PATCH https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Watchlist Name",
    "check_frequency": "weekly",
    "status": "active",
    "lists_to_monitor": ["ofac", "un", "eu"]
  }'

​
Request Parameters

All parameters are optional - only include fields you want to update:

​
Delete Watchlist

Remove a watchlist and all associated data.

​
Request

curl -X DELETE https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

{
  "status": "success",
  "message": "Watchlist deleted successfully"
}

​
Add Subject to Watchlist

Add a single subject to an existing watchlist.

​
Request

curl -X POST https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "New Subject",
    "identifier": "98765432",
    "identifier_type": "document"
  }'

​
Batch Add Subjects

Add multiple subjects to a watchlist in a single request.

​
Request

curl -X POST https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects/batch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjects": [
      {
        "full_name": "Subject 1",
        "identifier": "ID1",
        "identifier_type": "document"
      },
      {
        "full_name": "Subject 2",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet"
      }
    ]
  }'

​
Remove Subject from Watchlist

Remove a subject from a watchlist.

​
Request

curl -X DELETE https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Subject Fields

FieldTypeRequiredDescription
full_namestringYes*Full name of the subject
identifierstringNoDocument ID, wallet address, email, etc.
identifier_typestringNoType: “document”, “wallet”, “email”, etc.
*Required if no identifier is provided

​
Check Frequency Options

ValueDescription
dailyCheck all subjects once per day
weeklyCheck all subjects once per week
on_updateOnly check when subjects are added/updated

​
Status Codes

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Missing or invalid token
403Forbidden - Insufficient permissions
404Not Found - Watchlist or subject not found
500Internal Server Error

​
Alert Configuration

Configure alerts for watchlist events: 
{
  "on_new_match": true,           // Alert when new matches are found
  "on_status_change": true,       // Alert when subject status changes
  "webhook_url": "https://...",   // Optional webhook URL
  "notification_email": "..."     // Optional email address
}
When alerts are triggered, webhooks receive POST requests with match details in JSON format.