Skip to main content
GET
/
kyc
/
watchlists
List Watchlists
curl --request GET \
  --url https://api.example.com/kyc/watchlists

Endpoint

GET /kyc/watchlists

Authentication

Requires watchlist:list permission.

Query Parameters

active
boolean
Filter to show only active watchlists. Set to true to exclude paused watchlists.

Request Examples

Get All Watchlists

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

Get Only Active Watchlists

curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists?active=true" \
  -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"
    }
  ]
}

Response Fields

FieldTypeDescription
watchlist_idstringUnique identifier
namestringWatchlist name
statusstringactive or paused
subjects_countintegerNumber of subjects in watchlist
last_checked_atstring/nullLast screening timestamp (ISO 8601)
next_check_duenumber/nullNext check timestamp (Unix milliseconds)
check_frequencystringScreening frequency

Status Codes

CodeDescription
200Success
401Unauthorized
403Forbidden - Missing watchlist:list permission
500Internal Server Error