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

Documentation Index

Fetch the complete documentation index at: https://docs.compliance.legaltalent.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Add one or more subjects to an existing watchlist for ongoing monitoring. Subjects are automatically screened at the next scheduled check interval.
Seat-Based System: Each subject consumes one monitoring seat. Subjects have a TTL (Time-To-Live) and automatically expire after the configured duration (default: 365 days). Expired subjects free up seats automatically.

​
Add Single Subject

Add one subject at a time.

​
Endpoint

POST /kyc/watchlists/{watchlist_id}/subjects

​
Authentication

Requires watchlist:update permission.

​
Path Parameters

​
watchlist_id
string
required
The unique identifier of the watchlist

​
Request Body

​
Request Example

curl -X POST https://stg.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Jane Smith",
    "identifier": "98765432",
    "identifier_type": "document",
    "tags": ["priority", "manual-add"],
    "session_id": "sess_xyz789"
  }'

​
Response

{
  "status": "success",
  "data": {
    "subject_id": "770e8400-e29b-41d4-a716-446655440003",
    "expires_at": 1763789400,
    "duration_days": 365,
    "watchlist": {
      "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "High Risk Customers",
      "subjects": [...]
    }
  }
}

​
Response Fields

FieldTypeDescription
subject_idstringUnique identifier for the added subject
expires_atintegerUnix timestamp when the subject will expire
duration_daysintegerConfigured duration before expiration
watchlistobjectUpdated watchlist with all subjects

​
Add Multiple Subjects (Batch)

Add multiple subjects in a single request for efficiency.

​
Endpoint

POST /kyc/watchlists/{watchlist_id}/subjects/batch

​
Authentication

Requires watchlist:update permission.

​
Request Body

​
Request Example (Batch)

curl -X POST https://stg.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects/batch \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjects": [
      {
        "full_name": "Subject 1",
        "identifier": "ID1",
        "identifier_type": "document",
        "tags": ["batch-import", "priority"]
      },
      {
        "full_name": "Subject 2",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet",
        "tags": ["crypto"],
        "session_id": "sess_crypto001"
      },
      {
        "full_name": "Subject 3",
        "identifier": "TAX123456",
        "identifier_type": "tax_id",
        "tags": ["vendor"]
      }
    ]
  }'

​
Response

{
  "status": "success",
  "data": {
    "added_count": 3,
    "subject_ids": [
      "880e8400-e29b-41d4-a716-446655440004",
      "990e8400-e29b-41d4-a716-446655440005",
      "aa0e8400-e29b-41d4-a716-446655440006"
    ],
    "expires_at": 1763789400,
    "duration_days": 365,
    "watchlist": {
      "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Vendor Monitoring",
      "subjects": [...]
    }
  }
}

​
Batch Response Fields

FieldTypeDescription
added_countintegerNumber of subjects successfully added
subject_idsarrayUUIDs of all added subjects
expires_atintegerUnix timestamp when subjects will expire
duration_daysintegerConfigured duration before expiration
watchlistobjectUpdated watchlist with all subjects

​
Subject Fields

FieldTypeRequiredDescription
full_namestringYesFull name of the subject
identifierstringNoDocument ID, wallet address, email, etc.
identifier_typestringNoType: “document”, “wallet”, “email”, etc.
tagsarrayNoCustom tags for categorization and filtering
session_idstringNoSession ID if subject was created during onboarding

​
Common Identifier Types

TypeDescriptionExample
documentGovernment-issued ID”12345678”, “AB123456”
walletCryptocurrency wallet”0x742d35Cc…”
emailEmail address”user@example.com”
tax_idTax identification number”TAX-987654”
passportPassport number”AB1234567”

​
Error Responses

​
400 Bad Request

{
  "status": "error",
  "error": {
    "type": "ValidationError",
    "message": "Subject must have either full_name or identifier",
    "code": "VALIDATION_ERROR"
  }
}

​
402 Payment Required - No Seats Available

{
  "status": "error",
  "error": "No watchlist seats available. Please purchase more seats."
}
This error occurs when your tenant has used all available monitoring seats. Purchase additional seats to add more subjects. For batch operations, the error includes the specific counts: 
{
  "status": "error",
  "error": "Not enough watchlist seats. Available: 5, Requested: 10. Please purchase more seats."
}

​
404 Not Found

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

​
Status Codes

CodeDescription
201Created - Subject(s) added successfully
400Bad Request - Invalid subject data
401Unauthorized
402Payment Required - No seats available
403Forbidden - Missing watchlist:update permission
404Not Found - Watchlist not found
500Internal Server Error

​
Best Practices

When adding multiple subjects, always use the batch endpoint (/subjects/batch) instead of making multiple single-subject calls. This:
  • Reduces API calls and stays within rate limits
  • Improves performance
  • Simplifies error handling
While full_name alone is sufficient, providing identifiers improves matching accuracy:
  • More precise matches
  • Reduces false positives
  • Better audit trail
Use specific identifier types to help with matching:
  • document for government IDs
  • wallet for crypto addresses
  • passport for passport numbers
  • tax_id for tax identifiers
For subjects added with check_frequency: "on_update", the watchlist will screen them immediately. For daily or weekly frequencies, subjects are screened at the next scheduled check.You can also trigger monitoring manually to get immediate results.
Subjects automatically expire after a configured period (default: 365 days). The expires_at field in the response shows when each subject will be removed. Plan renewals accordingly to maintain continuous monitoring.
Before adding subjects, verify you have available seats. Use the Usage API to check your current seat consumption and avoid 402 errors.

​
Next Steps