Get Watchlist Details - KYC API Documentation

Endpoint

GET /kyc/watchlists/{watchlist_id}

Authentication

Requires watchlist:read permission.

Path Parameters

watchlist_id

string

required

The unique identifier of the watchlist

Request Example

curl -X GET https://stg.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",
        "tags": ["vip", "high-risk"],
        "session_id": "sess_abc123",
        "added_at": "2024-11-22T10:30:00Z",
        "expires_at": 1763789400
      }
    ],
    "tags": ["compliance", "q4-review"],
    "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
    },
    "status": "active",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
`watchlist_id`	string	Unique identifier
`tenant_id`	string	Your tenant ID
`name`	string	Watchlist name
`subjects`	array	Full list of monitored subjects
`lists_to_monitor`	array	Lists being checked
`check_frequency`	string	Screening frequency
`last_checked_at`	string/null	Last check timestamp
`next_check_due`	number/null	Next check timestamp (Unix ms)
`last_results`	object/null	Most recent screening results
`alert_config`	object	Alert configuration
`tags`	array	Custom tags for categorization
`status`	string	`active` or `paused`
`created_at`	string	Creation timestamp
`updated_at`	string	Last update timestamp

Subject Fields

Field	Type	Description
`subject_id`	string	Unique identifier
`full_name`	string	Subject’s full name
`identifier`	string/null	Document ID, wallet, etc.
`identifier_type`	string/null	Type of identifier
`tags`	array	Custom tags for categorization
`session_id`	string/null	Session ID if created during onboarding
`added_at`	string	When added to watchlist
`expires_at`	integer	Unix timestamp for TTL expiration

Error Responses

404 Not Found

{
  "status": "error",
  "error": {
    "type": "NotFoundError",
    "message": "Watchlist not found",
    "code": "WATCHLIST_NOT_FOUND"
  }
}

Status Codes

Code	Description
200	Success
401	Unauthorized
403	Forbidden - Missing `watchlist:read` permission
404	Not Found
500	Internal Server Error

Next Steps

Trigger immediate monitoring to run a screening check
Add more subjects to the watchlist
Update configuration to change monitoring settings

​Endpoint

​Authentication

​Path Parameters

​Request Example

​Response

​Response Fields

​Subject Fields

​Error Responses

​404 Not Found

​Status Codes

​Next Steps

Endpoint

Authentication

Path Parameters

Request Example

Response

Response Fields

Subject Fields

Error Responses

404 Not Found

Status Codes

Next Steps