Remove Subject
curl --request DELETE \
--url https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}import requests
url = "https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}"
response = requests.delete(url)
print(response.text)const options = {method: 'DELETE'};
fetch('https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}"
req, _ := http.NewRequest("DELETE", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
response = http.request(request)
puts response.read_bodyWatchlists
Remove Subject
Remove a subject from a watchlist
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}import requests
url = "https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}"
response = requests.delete(url)
print(response.text)const options = {method: 'DELETE'};
fetch('https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}"
req, _ := http.NewRequest("DELETE", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.delete("https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/kyc/watchlists/{watchlist_id}/subjects/{subject_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(url)
response = http.request(request)
puts response.read_bodyEndpoint
DELETE /kyc/watchlists/{watchlist_id}/subjects/{subject_id}
Authentication
Requireswatchlist:update permission.
Path Parameters
string
required
The unique identifier of the watchlist
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
| Code | Description |
|---|---|
| 200 | Success - Subject removed |
| 401 | Unauthorized |
| 403 | Forbidden - Missing watchlist:update permission |
| 404 | Not Found - Watchlist or subject not found |
| 500 | Internal 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
Get Subject ID First
Get Subject ID First
To remove a subject, you need their
subject_id. Get it from the Get Watchlist endpoint which returns all subjects with their IDs.Preserve Audit Trail
Preserve Audit Trail
Before removing subjects, export watchlist data for compliance and audit purposes using the Get Watchlist endpoint.
Batch Operations
Batch Operations
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
- Add new subjects to replace removed ones
- Get watchlist details to verify removal
- Update watchlist configuration if needed