> ## 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.

# Watchlists

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

<RequestExample>
  ```bash theme={null}
  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"
    }'
  ```
</RequestExample>

### Request Parameters

<ParamFields>
  <ParamField name="name" type="string" required description="Watchlist name" />

  <ParamField name="subjects" type="array" description="Initial subjects to monitor (optional, can add later)" />

  <ParamField name="lists_to_monitor" type="array" description="Lists to check against (default: all available lists)" />

  <ParamField name="check_frequency" type="string" description="Check frequency: 'daily', 'weekly', or 'on_update' (default: 'daily')" />

  <ParamField name="alert_config" type="object" description="Alert configuration (optional)" />

  <ParamField name="status" type="string" description="Initial status: 'active' or 'paused' (default: 'active')" />

  <ParamField name="tags" type="array" description="Custom tags for categorizing the watchlist (optional)" />
</ParamFields>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "data": {
      "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
      "message": "Watchlist created successfully"
    }
  }
  ```
</ResponseExample>

## List Watchlists

Retrieve all watchlists for your tenant with optional filtering.

### Request

<RequestExample>
  ```bash theme={null}
  # 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"
  ```
</RequestExample>

### 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

<ResponseExample>
  ```json theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

## Get Watchlist Details

Retrieve detailed information about a specific watchlist.

### Request

<RequestExample>
  ```bash theme={null}
  curl -X GET https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## Update Watchlist

Update watchlist configuration.

### Request

<RequestExample>
  ```bash theme={null}
  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"]
    }'
  ```
</RequestExample>

### Request Parameters

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

<ParamFields>
  <ParamField name="name" type="string" description="New watchlist name" />

  <ParamField name="lists_to_monitor" type="array" description="Lists to check against" />

  <ParamField name="check_frequency" type="string" description="Check frequency: 'daily', 'weekly', or 'on_update'" />

  <ParamField name="alert_config" type="object" description="Alert configuration" />

  <ParamField name="status" type="string" description="Status: 'active' or 'paused'" />

  <ParamField name="tags" type="array" description="Custom tags for categorizing the watchlist" />
</ParamFields>

## Delete Watchlist

Remove a watchlist and all associated data.

### Request

<RequestExample>
  ```bash theme={null}
  curl -X DELETE https://dev.kyc.legaltalent.ai/kyc/watchlists/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "message": "Watchlist deleted successfully"
  }
  ```
</ResponseExample>

## 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

<RequestExample>
  ```bash theme={null}
  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"
    }'
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "data": {
      "subject_id": "770e8400-e29b-41d4-a716-446655440002",
      "expires_at": 1763814600,
      "duration_days": 365,
      "watchlist": { "..." }
    }
  }
  ```
</ResponseExample>

## 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

<RequestExample>
  ```bash theme={null}
  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"
        }
      ]
    }'
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "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": { "..." }
    }
  }
  ```
</ResponseExample>

## List Subjects

Retrieve all subjects from a watchlist with optional tag filtering.

### Request

<RequestExample>
  ```bash theme={null}
  # 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"
  ```
</RequestExample>

### Query Parameters

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

### Response

<ResponseExample>
  ```json theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

## 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

<RequestExample>
  ```bash theme={null}
  curl -X GET "https://dev.kyc.legaltalent.ai/kyc/watchlists/subjects?session_id=sess_abc123" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</RequestExample>

### Query Parameters

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

### Response

<ResponseExample>
  ```json theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

<Info>
  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.
</Info>

## Get Unique Tags

Retrieve all unique tags from active subjects for autocomplete functionality.

### Request

<RequestExample>
  ```bash theme={null}
  curl -X GET "https://dev.kyc.legaltalent.ai/kyc/watchlists/tags" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "data": {
      "tags": [
        "batch-import",
        "crypto",
        "high-risk",
        "priority",
        "reviewed",
        "vip"
      ],
      "count": 6
    }
  }
  ```
</ResponseExample>

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

## Update Subject Tags

Update the tags for a specific subject in a watchlist.

### Request

<RequestExample>
  ```bash theme={null}
  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"]
    }'
  ```
</RequestExample>

### Request Parameters

<ParamFields>
  <ParamField name="tags" type="array" required description="New tags for the subject (replaces existing tags)" />
</ParamFields>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "data": {
      "subject_id": "660e8400-e29b-41d4-a716-446655440001",
      "tags": ["reviewed", "cleared", "low-risk"],
      "message": "Subject tags updated successfully"
    }
  }
  ```
</ResponseExample>

## Remove Subject from Watchlist

Remove a subject from a watchlist.

### Request

<RequestExample>
  ```bash theme={null}
  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"
  ```
</RequestExample>

### Response

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "data": {
      "message": "Subject deleted successfully",
      "watchlist": { "..." }
    }
  }
  ```
</ResponseExample>

## 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:

```json theme={null}
{
  "on_new_match": true,           // Alert when new matches are found
  "on_status_change": true        // Alert when subject status changes
}
```

<Info>
  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.
</Info>

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