Add Subjects - KYC API Documentation

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

Field	Type	Description
`subject_id`	string	Unique identifier for the added subject
`expires_at`	integer	Unix timestamp when the subject will expire
`duration_days`	integer	Configured duration before expiration
`watchlist`	object	Updated 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

Field	Type	Description
`added_count`	integer	Number of subjects successfully added
`subject_ids`	array	UUIDs of all added subjects
`expires_at`	integer	Unix timestamp when subjects will expire
`duration_days`	integer	Configured duration before expiration
`watchlist`	object	Updated watchlist with all subjects

Subject Fields

Field	Type	Required	Description
`full_name`	string	Yes	Full name of the subject
`identifier`	string	No	Document ID, wallet address, email, etc.
`identifier_type`	string	No	Type: “document”, “wallet”, “email”, etc.
`tags`	array	No	Custom tags for categorization and filtering
`session_id`	string	No	Session ID if subject was created during onboarding

Common Identifier Types

Type	Description	Example
`document`	Government-issued ID	”12345678”, “AB123456”
`wallet`	Cryptocurrency wallet	”0x742d35Cc…”
`email`	Email address	”user@example.com”
`tax_id`	Tax identification number	”TAX-987654”
`passport`	Passport 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

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

Best Practices

Use Batch for Multiple Subjects

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

Provide Identifiers When Possible

While full_name alone is sufficient, providing identifiers improves matching accuracy:

More precise matches
Reduces false positives
Better audit trail

Use Descriptive Identifier Types

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

Check Immediately After Adding

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.

Understand Subject Expiration

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.

Monitor Seat Usage

Before adding subjects, verify you have available seats. Use the Usage API to check your current seat consumption and avoid 402 errors.

Next Steps

Remove subjects when no longer needed
Get watchlist details to view all subjects
Monitor screening results with Usage API

​Overview

​Add Single Subject

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Request Example

​Response

​Response Fields

​Add Multiple Subjects (Batch)

​Endpoint

​Authentication

​Request Body

​Request Example (Batch)

​Response

​Batch Response Fields

​Subject Fields

​Common Identifier Types

​Error Responses

​400 Bad Request

​402 Payment Required - No Seats Available

​404 Not Found

​Status Codes

​Best Practices

​Next Steps

Overview

Add Single Subject

Endpoint

Authentication

Path Parameters

Request Body

Request Example

Response

Response Fields

Add Multiple Subjects (Batch)

Endpoint

Authentication

Request Body

Request Example (Batch)

Response

Batch Response Fields

Subject Fields

Common Identifier Types

Error Responses

400 Bad Request

402 Payment Required - No Seats Available

404 Not Found

Status Codes

Best Practices

Next Steps