Skip to main content
GET
/
kyc
/
watchlists
/
{watchlist_id}
/
subjects
List Subjects
curl --request GET \
  --url https://api.example.com/kyc/watchlists/{watchlist_id}/subjects

​
Endpoint

GET /kyc/watchlists/{watchlist_id}/subjects

​
Authentication

Requires watchlist:read permission.

​
Path Parameters

​
watchlist_id
string
required
The unique identifier of the watchlist

​
Query Parameters

​
tags
string
Comma-separated list of tags to filter by. Returns subjects that have any of the specified tags.Example: tags=priority,vip

​
Request Examples

​
Get All Subjects

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

​
Filter by Tags

curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects?tags=priority,vip" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "subjects": [
      {
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["priority", "vip"],
        "session_id": "sess_abc123",
        "added_at": "2024-11-22T10:30:00Z",
        "expires_at": 1763789400
      },
      {
        "subject_id": "770e8400-e29b-41d4-a716-446655440002",
        "full_name": "Jane Smith",
        "identifier": "98765432",
        "identifier_type": "document",
        "tags": ["priority"],
        "session_id": null,
        "added_at": "2024-11-23T14:00:00Z",
        "expires_at": 1763875800
      }
    ],
    "count": 2
  }
}

​
Response Fields

FieldTypeDescription
watchlist_idstringThe watchlist identifier
subjectsarrayList of subject objects
countintegerNumber of subjects returned

​
Subject Object Fields

FieldTypeDescription
subject_idstringUnique identifier
full_namestringSubject’s full name
identifierstring/nullDocument ID, wallet, etc.
identifier_typestring/nullType of identifier
tagsarrayCustom tags for categorization
session_idstring/nullSession ID if created during onboarding
added_atstringWhen added to watchlist (ISO 8601)
expires_atintegerUnix timestamp for TTL expiration

​
Error Responses

​
404 Not Found

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

​
Status Codes

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

​
Use Cases

Use tag filtering to quickly retrieve subjects that need immediate attention:
curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists/{id}/subjects?tags=high-priority,urgent" \
  -H "Authorization: Bearer YOUR_TOKEN"
Retrieve subjects that were added during onboarding sessions by checking the session_id field in the response.
Use the expires_at field to identify subjects nearing expiration and plan renewals.

​
Next Steps