Watchlists - KYC API Documentation

curl -X POST https://dev.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Risk Customers",
    "subjects": [
      {
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["vip", "high-risk"],
        "session_id": "sess_abc123"
      },
      {
        "full_name": "Jane Smith",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet",
        "tags": ["crypto"]
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true
    },
    "tags": ["compliance", "q4-review"],
    "status": "active"
  }'

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Watchlist created successfully"
  }
}

GET

kyc

watchlists

curl -X POST https://dev.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Risk Customers",
    "subjects": [
      {
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["vip", "high-risk"],
        "session_id": "sess_abc123"
      },
      {
        "full_name": "Jane Smith",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet",
        "tags": ["crypto"]
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true
    },
    "tags": ["compliance", "q4-review"],
    "status": "active"
  }'

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Watchlist created successfully"
  }
}

Manage watchlists for ongoing monitoring of entities against KYC watchlists. Watchlists automatically check subjects at configured intervals and alert on matches or status changes.

Overview

Watchlists allow you to:

Monitor multiple entities continuously
Receive alerts when matches are found
Track changes in entity status over time
Schedule automatic checks (daily, weekly, or on update)
Organize subjects with custom tags
Link subjects to onboarding sessions via session_id

Endpoints

Method	Endpoint	Permission Required
`POST`	`/kyc/watchlists`	`watchlist:create`
`GET`	`/kyc/watchlists`	`watchlist:list`
`GET`	`/kyc/watchlists/{watchlist_id}`	`watchlist:read`
`PATCH`	`/kyc/watchlists/{watchlist_id}`	`watchlist:update`
`DELETE`	`/kyc/watchlists/{watchlist_id}`	`watchlist:delete`
`POST`	`/kyc/watchlists/{watchlist_id}/subjects`	`watchlist:update`
`POST`	`/kyc/watchlists/{watchlist_id}/subjects/batch`	`watchlist:update`
`GET`	`/kyc/watchlists/{watchlist_id}/subjects`	`watchlist:read`
`GET`	`/kyc/watchlists/subjects?session_id=...`	`watchlist:read`
`GET`	`/kyc/watchlists/tags`	`watchlist:read`
`PATCH`	`/kyc/watchlists/{watchlist_id}/subjects/{subject_id}`	`watchlist:update`
`DELETE`	`/kyc/watchlists/{watchlist_id}/subjects/{subject_id}`	`watchlist:update`
`POST`	`/kyc/watchlists/{watchlist_id}/monitor`	`watchlist:run`

Create Watchlist

Create a new watchlist with subjects to monitor.

Request

curl -X POST https://dev.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Risk Customers",
    "subjects": [
      {
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["vip", "high-risk"],
        "session_id": "sess_abc123"
      },
      {
        "full_name": "Jane Smith",
        "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "identifier_type": "wallet",
        "tags": ["crypto"]
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true
    },
    "tags": ["compliance", "q4-review"],
    "status": "active"
  }'

Request Parameters

Response

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "Watchlist created successfully"
  }
}

List Watchlists

Retrieve all watchlists for your tenant with optional filtering.

Request

# List all watchlists
curl -X GET https://dev.kyc.legaltalent.ai/kyc/watchlists \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by active status only
curl -X GET "https://dev.kyc.legaltalent.ai/kyc/watchlists?active=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by tags (comma-separated)
curl -X GET "https://dev.kyc.legaltalent.ai/kyc/watchlists?tags=compliance,high-risk" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Type	Description
`active`	boolean	If `true`, only return watchlists with status=‘active’
`tags`	string	Comma-separated list of tags to filter by (matches if any tag is present)

Response

{
  "status": "success",
  "data": {
    "watchlists": [
      {
        "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "High Risk Customers",
        "status": "active",
        "tags": ["compliance", "q4-review"],
        "last_checked_at": "2024-11-22T09:00:00Z",
        "next_check_due": 1732278600000,
        "check_frequency": "daily"
      },
      {
        "watchlist_id": "660e8400-e29b-41d4-a716-446655440002",
        "name": "Vendor Watchlist",
        "status": "paused",
        "tags": ["vendors"],
        "last_checked_at": null,
        "next_check_due": null,
        "check_frequency": "weekly"
      }
    ],
    "count": 2
  }
}

Get Watchlist Details

Retrieve detailed information about a specific watchlist.

Request

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

Response

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "tenant123",
    "name": "High Risk Customers",
    "subjects": [
      {
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["vip", "high-risk"],
        "session_id": "sess_abc123",
        "added_at": "2024-11-22T10:30:00Z",
        "expires_at": 1763814600
      }
    ],
    "lists_to_monitor": ["ofac", "un"],
    "check_frequency": "daily",
    "last_checked_at": "2024-11-22T09:00:00Z",
    "next_check_due": 1732278600000,
    "last_results": {
      "checked_at": "2024-11-22T09:00:00Z",
      "subjects_checked": 5,
      "matches_found": 0,
      "new_matches": 0,
      "s3_snapshot_key": "snapshots/tenant123/550e8400/2024-11-22T09:00:00Z.json"
    },
    "alert_config": {
      "on_new_match": true,
      "on_status_change": true
    },
    "tags": ["compliance", "q4-review"],
    "status": "active",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}

Update Watchlist

Update watchlist configuration.

Request

curl -X PATCH https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Watchlist Name",
    "check_frequency": "weekly",
    "status": "active",
    "lists_to_monitor": ["ofac", "un", "eu"],
    "tags": ["updated", "priority"]
  }'

Request Parameters

All parameters are optional - only include fields you want to update:

Delete Watchlist

Remove a watchlist and all associated data.

Request

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

Response

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

Add Subject to Watchlist

Add a single subject to an existing watchlist. Subjects are automatically assigned a TTL-based expiration based on your tenant configuration.

Request

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

Response

{
  "status": "success",
  "data": {
    "subject_id": "770e8400-e29b-41d4-a716-446655440002",
    "expires_at": 1763814600,
    "duration_days": 365,
    "watchlist": { "..." }
  }
}

Batch Add Subjects

Add multiple subjects to a watchlist in a single request. All subjects are assigned the same expiration time based on your tenant configuration.

Request

curl -X POST https://dev.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_batch001"
      }
    ]
  }'

Response

{
  "status": "success",
  "data": {
    "added_count": 2,
    "subject_ids": [
      "770e8400-e29b-41d4-a716-446655440003",
      "770e8400-e29b-41d4-a716-446655440004"
    ],
    "expires_at": 1763814600,
    "duration_days": 365,
    "watchlist": { "..." }
  }
}

List Subjects

Retrieve all subjects from a watchlist with optional tag filtering.

Request

# List all subjects
curl -X GET https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects \
  -H "Authorization: Bearer YOUR_TOKEN"

# Filter by tags (comma-separated)
curl -X GET "https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000/subjects?tags=priority,vip" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Type	Description
`tags`	string	Comma-separated list of tags to filter by (matches if any tag is present)

Response

{
  "status": "success",
  "data": {
    "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
    "subjects": [
      {
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["priority", "vip"],
        "session_id": "sess_abc123",
        "added_at": "2024-11-22T10:30:00Z",
        "expires_at": 1763814600
      }
    ],
    "count": 1
  }
}

Search Subjects by Session ID

Find all subjects linked to a specific session across all watchlists. This is useful for finding subjects that were created during a specific onboarding session.

Request

curl -X GET "https://dev.kyc.legaltalent.ai/kyc/watchlists/subjects?session_id=sess_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

Parameter	Type	Required	Description
`session_id`	string	Yes	Session ID to search for

Response

{
  "status": "success",
  "data": {
    "session_id": "sess_abc123",
    "subjects": [
      {
        "tenant_id": "tenant123",
        "subject_id": "660e8400-e29b-41d4-a716-446655440001",
        "full_name": "John Doe",
        "identifier": "12345678",
        "identifier_type": "document",
        "tags": ["vip", "high-risk"],
        "session_id": "sess_abc123",
        "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
        "added_at": "2024-11-22T10:30:00Z",
        "expires_at": 1763814600
      }
    ],
    "count": 1
  }
}

This endpoint queries the subjects table using a dedicated GSI (session-index), which provides efficient lookups by session ID. Only active (non-expired) subjects are returned.

Get Unique Tags

Retrieve all unique tags from active subjects for autocomplete functionality.

Request

curl -X GET "https://dev.kyc.legaltalent.ai/kyc/watchlists/tags" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "success",
  "data": {
    "tags": [
      "batch-import",
      "crypto",
      "high-risk",
      "priority",
      "reviewed",
      "vip"
    ],
    "count": 6
  }
}

Tags are returned in alphabetical order. Use this endpoint to power autocomplete fields for tag filtering in your UI.

Update Subject Tags

Update the tags for a specific subject in a watchlist.

Request

curl -X PATCH https://dev.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"]
  }'

Request Parameters

Response

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

Remove Subject from Watchlist

Remove a subject from a watchlist.

Request

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

Response

{
  "status": "success",
  "data": {
    "message": "Subject deleted successfully",
    "watchlist": { "..." }
  }
}

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

Response-only Fields

These fields are returned in responses but cannot be set directly:

Field	Type	Description
`subject_id`	string	Unique identifier (UUID)
`added_at`	string	ISO timestamp when the subject was added
`expires_at`	integer	Unix timestamp for TTL-based auto-deletion

Check Frequency Options

Value	Description
`daily`	Check all subjects once per day
`weekly`	Check all subjects once per week
`on_update`	Only check when subjects are added/updated

Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid token
403	Forbidden - Insufficient permissions
404	Not Found - Watchlist or subject not found
500	Internal Server Error

Alert Configuration

Configure when to send alerts for watchlist events:

{
  "on_new_match": true,           // Alert when new matches are found
  "on_status_change": true        // Alert when subject status changes
}

Notification channels (webhooks, emails) are configured at the tenant level, not per-watchlist. The alert_config only controls when to send alerts, not where. Contact support to configure your notification channels.

When alerts are triggered, webhooks receive POST requests with match details in JSON format.

​Overview

​Endpoints

​Create Watchlist

​Request

​Request Parameters

​Response

​List Watchlists

​Request

​Query Parameters

​Response

​Get Watchlist Details

​Request

​Response

​Update Watchlist

​Request

​Request Parameters

​Delete Watchlist

​Request

​Response

​Add Subject to Watchlist

​Request

​Response

​Batch Add Subjects

​Request

​Response

​List Subjects

​Request

​Query Parameters

​Response

​Search Subjects by Session ID

​Request

​Query Parameters

​Response

​Get Unique Tags

​Request

​Response

​Update Subject Tags

​Request

​Request Parameters

​Response

​Remove Subject from Watchlist

​Request

​Response

​Subject Fields

​Response-only Fields

​Check Frequency Options

​Status Codes

​Alert Configuration

Overview

Endpoints

Create Watchlist

Request

Request Parameters

Response

List Watchlists

Request

Query Parameters

Response

Get Watchlist Details

Request

Response

Update Watchlist

Request

Request Parameters

Delete Watchlist

Request

Response

Add Subject to Watchlist

Request

Response

Batch Add Subjects

Request

Response

List Subjects

Request

Query Parameters

Response

Search Subjects by Session ID

Request

Query Parameters

Response

Get Unique Tags

Request

Response

Update Subject Tags

Request

Request Parameters

Response

Remove Subject from Watchlist

Request

Response

Subject Fields

Response-only Fields

Check Frequency Options

Status Codes

Alert Configuration