Skip to main content
DELETE
/
kyc
/
watchlists
/
{watchlist_id}
Delete Watchlist
curl --request DELETE \
  --url https://api.example.com/kyc/watchlists/{watchlist_id}

​
Endpoint

DELETE /kyc/watchlists/{watchlist_id}

​
Authentication

Requires watchlist:delete permission.

​
Path Parameters

​
watchlist_id
string
required
The unique identifier of the watchlist to delete

​
Request Example

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

​
Response

{
  "status": "success",
  "message": "Watchlist deleted successfully"
}

​
Error Responses

​
404 Not Found

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

​
Important Notes

This action is permanent and cannot be undone.Deleting a watchlist will:
  • Remove the watchlist configuration
  • Delete all subjects from the watchlist
  • Cancel scheduled checks
  • Remove historical screening data
  • Stop all alerts and notifications
Alternative: Pause Instead of DeleteIf you want to temporarily stop monitoring without losing data, consider updating the status to paused instead of deleting.

​
Status Codes

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

​
Best Practices

  • Export data first: Use the Get Watchlist endpoint to retrieve and save watchlist data before deletion
  • Pause instead: For temporary suspension, use status: "paused" to preserve data
  • Verify ID: Double-check the watchlist_id to avoid accidental deletion
  • Log deletions: Maintain audit logs of watchlist deletions for compliance