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.
tags
string
Comma-separated list of tags to filter by. Returns watchlists that have any of the specified tags.Example: tags=compliance,high-priority

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"

Filter by Tags

curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists?tags=compliance,high-priority" \
  -H "Authorization: Bearer YOUR_TOKEN"

Combine Filters

curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists?active=true&tags=compliance" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "success",
  "data": {
    "watchlists": [
      {
        "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "High Risk Customers",
        "status": "active",
        "tags": ["compliance", "high-priority"],
        "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",
        "tags": ["vendors"],
        "last_checked_at": null,
        "next_check_due": null,
        "check_frequency": "weekly"
      }
    ],
    "count": 2
  }
}

Response Fields

FieldTypeDescription
watchlistsarrayList of watchlist objects
countintegerTotal number of watchlists returned

Watchlist Object Fields

FieldTypeDescription
watchlist_idstringUnique identifier
namestringWatchlist name
statusstringactive or paused
tagsarrayCustom tags for categorization
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