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

# Get Watchlist Details

> Retrieve detailed information about a specific watchlist

## Endpoint

```
GET /kyc/watchlists/{watchlist_id}
```

## Authentication

Requires `watchlist:read` permission.

## Path Parameters

<ParamField path="watchlist_id" type="string" required>
  The unique identifier of the watchlist
</ParamField>

## Request Example

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

## Response

```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": 1763789400
      }
    ],
    "tags": ["compliance", "q4-review"],
    "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
    },
    "status": "active",
    "created_at": "2024-11-22T10:30:00Z",
    "updated_at": "2024-11-22T10:30:00Z"
  }
}
```

## Response Fields

| Field              | Type        | Description                     |
| ------------------ | ----------- | ------------------------------- |
| `watchlist_id`     | string      | Unique identifier               |
| `tenant_id`        | string      | Your tenant ID                  |
| `name`             | string      | Watchlist name                  |
| `subjects`         | array       | Full list of monitored subjects |
| `lists_to_monitor` | array       | Lists being checked             |
| `check_frequency`  | string      | Screening frequency             |
| `last_checked_at`  | string/null | Last check timestamp            |
| `next_check_due`   | number/null | Next check timestamp (Unix ms)  |
| `last_results`     | object/null | Most recent screening results   |
| `alert_config`     | object      | Alert configuration             |
| `tags`             | array       | Custom tags for categorization  |
| `status`           | string      | `active` or `paused`            |
| `created_at`       | string      | Creation timestamp              |
| `updated_at`       | string      | Last update timestamp           |

### Subject Fields

| Field             | Type        | Description                             |
| ----------------- | ----------- | --------------------------------------- |
| `subject_id`      | string      | Unique identifier                       |
| `full_name`       | string      | Subject's full name                     |
| `identifier`      | string/null | Document ID, wallet, etc.               |
| `identifier_type` | string/null | Type of identifier                      |
| `tags`            | array       | Custom tags for categorization          |
| `session_id`      | string/null | Session ID if created during onboarding |
| `added_at`        | string      | When added to watchlist                 |
| `expires_at`      | integer     | Unix timestamp for TTL expiration       |

## Error Responses

### 404 Not Found

```json theme={null}
{
  "status": "error",
  "error": {
    "type": "NotFoundError",
    "message": "Watchlist not found",
    "code": "WATCHLIST_NOT_FOUND"
  }
}
```

## Status Codes

| Code | Description                                     |
| ---- | ----------------------------------------------- |
| 200  | Success                                         |
| 401  | Unauthorized                                    |
| 403  | Forbidden - Missing `watchlist:read` permission |
| 404  | Not Found                                       |
| 500  | Internal Server Error                           |

## Next Steps

* [Trigger immediate monitoring](/api-reference/watchlists/trigger-monitoring) to run a screening check
* [Add more subjects](/api-reference/watchlists/add-subjects) to the watchlist
* [Update configuration](/api-reference/watchlists/update) to change monitoring settings