Skip to main content
DELETE
/
kyc
/
watchlists
/
{watchlist_id}
/
subjects
/
{subject_id}
Remove Subject
curl --request DELETE \
  --url https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}

​
Endpoint

DELETE /kyc/watchlists/{watchlist_id}/subjects/{subject_id}

​
Authentication

Requires watchlist:update permission.

​
Path Parameters

​
watchlist_id
string
required
The unique identifier of the watchlist
​
subject_id
string
required
The unique identifier of the subject to remove

​
Request Example

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

​
Response

{
  "status": "success",
  "message": "Subject removed from watchlist successfully"
}

​
Error Responses

​
404 Not Found - Watchlist

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

​
404 Not Found - Subject

{
  "status": "error",
  "error": {
    "type": "NotFoundError",
    "message": "Subject not found in watchlist",
    "code": "SUBJECT_NOT_FOUND"
  }
}

​
Status Codes

CodeDescription
200Success - Subject removed
401Unauthorized
403Forbidden - Missing watchlist:update permission
404Not Found - Watchlist or subject not found
500Internal Server Error

​
Important Notes

What Happens After RemovalWhen a subject is removed from a watchlist:
  • The subject is immediately excluded from future checks
  • Historical screening data for this subject is preserved
  • No alerts will be sent for this subject
  • The subject can be re-added later if needed

​
Best Practices

To remove a subject, you need their subject_id. Get it from the Get Watchlist endpoint which returns all subjects with their IDs.
Before removing subjects, export watchlist data for compliance and audit purposes using the Get Watchlist endpoint.
Currently, subjects must be removed one at a time. If you need to remove many subjects, consider deleting and recreating the watchlist or pausing it.

​
Example Workflow

Get subject IDs, then remove: 
# Step 1: Get watchlist details to find subject_id
curl -X GET https://stg.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

# Response includes subjects array with subject_id values
# {
#   "subjects": [
#     {"subject_id": "660e8400-...", "full_name": "John Doe"},
#     {"subject_id": "770e8400-...", "full_name": "Jane Smith"}
#   ]
# }

# Step 2: Remove specific subject
curl -X DELETE https://stg.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Next Steps