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

​
Endpoint

PATCH /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 update

​
Request Body

​
Request Example

curl -X PATCH https://stg.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects/660e8400-e29b-41d4-a716-446655440001 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["reviewed", "cleared", "low-risk"]
  }'

​
Additional Examples

​
Mark as Reviewed

curl -X PATCH https://stg.kyc.legaltalent.ai/kyc/watchlists/{watchlist_id}/subjects/{subject_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["reviewed", "approved"]
  }'

​
Mark as High Risk

curl -X PATCH https://stg.kyc.legaltalent.ai/kyc/watchlists/{watchlist_id}/subjects/{subject_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["high-risk", "requires-review", "escalated"]
  }'

​
Clear All Tags

curl -X PATCH https://stg.kyc.legaltalent.ai/kyc/watchlists/{watchlist_id}/subjects/{subject_id} \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": []
  }'

​
Response

{
  "status": "success",
  "data": {
    "subject_id": "660e8400-e29b-41d4-a716-446655440001",
    "tags": ["reviewed", "cleared", "low-risk"],
    "message": "Subject tags updated successfully"
  }
}

​
Response Fields

FieldTypeDescription
subject_idstringThe updated subject’s identifier
tagsarrayThe new tags applied to the subject
messagestringSuccess confirmation message

​
Error Responses

​
400 Bad Request

{
  "status": "error",
  "error": {
    "type": "ValidationError",
    "message": "Tags field is required",
    "code": "VALIDATION_ERROR"
  }
}

​
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
400Bad Request - Invalid or missing tags
401Unauthorized
403Forbidden - Missing watchlist:update permission
404Not Found - Watchlist or subject not found
500Internal Server Error

​
Use Cases

Use tags to track subjects through your compliance review process:
  1. Subject added with ["pending-review"]
  2. Analyst reviews → update to ["in-review", "analyst-john"]
  3. Approved → update to ["reviewed", "approved", "2024-q4"]
Categorize subjects by risk level for filtering and reporting:
  • ["low-risk", "verified"]
  • ["medium-risk", "requires-monitoring"]
  • ["high-risk", "escalated", "pep"]
After reviewing a batch of subjects, update their tags to reflect the review status. Use the List Subjects endpoint to find subjects by tag, then update each one.

​
Best Practices

Tags are replaced, not merged. To add a tag while keeping existing ones, first retrieve the current tags using Get Watchlist Details, then include all desired tags in the update.
  • Use consistent tag naming conventions across your organization
  • Consider using prefixes for categories: status-, risk-, reviewer-
  • Document your tag taxonomy for team alignment
  • Use tags to enable filtering in the List Subjects endpoint

​
Next Steps