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

# List Watchlists

> Retrieve all watchlists for your tenant

## Endpoint

```
GET /kyc/watchlists
```

## Authentication

Requires `watchlist:list` permission.

## Query Parameters

<ParamField query="active" type="boolean">
  Filter to show only active watchlists. Set to `true` to exclude paused watchlists.
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated list of tags to filter by. Returns watchlists that have any of the specified tags.

  Example: `tags=compliance,high-priority`
</ParamField>

## Request Examples

### Get All Watchlists

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

### Get Only Active Watchlists

```bash theme={null}
curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists?active=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Filter by Tags

```bash theme={null}
curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists?tags=compliance,high-priority" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Combine Filters

```bash theme={null}
curl -X GET "https://stg.kyc.legaltalent.ai/kyc/watchlists?active=true&tags=compliance" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Response

```json theme={null}
{
  "status": "success",
  "data": {
    "watchlists": [
      {
        "watchlist_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "High Risk Customers",
        "status": "active",
        "tags": ["compliance", "high-priority"],
        "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
  }
}
```

## Response Fields

| Field        | Type    | Description                         |
| ------------ | ------- | ----------------------------------- |
| `watchlists` | array   | List of watchlist objects           |
| `count`      | integer | Total number of watchlists returned |

### Watchlist Object Fields

| Field             | Type        | Description                              |
| ----------------- | ----------- | ---------------------------------------- |
| `watchlist_id`    | string      | Unique identifier                        |
| `name`            | string      | Watchlist name                           |
| `status`          | string      | `active` or `paused`                     |
| `tags`            | array       | Custom tags for categorization           |
| `last_checked_at` | string/null | Last screening timestamp (ISO 8601)      |
| `next_check_due`  | number/null | Next check timestamp (Unix milliseconds) |
| `check_frequency` | string      | Screening frequency                      |

## Status Codes

| Code | Description                                     |
| ---- | ----------------------------------------------- |
| 200  | Success                                         |
| 401  | Unauthorized                                    |
| 403  | Forbidden - Missing `watchlist:list` permission |
| 500  | Internal Server Error                           |