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

# Add Subjects

> Add subjects to a watchlist individually or in batch

## Overview

Add one or more subjects to an existing watchlist for ongoing monitoring. Subjects are automatically screened at the next scheduled check interval.

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

## Add Single Subject

Add one subject at a time.

### Endpoint

```
POST /kyc/watchlists/{watchlist_id}/subjects
```

### Authentication

Requires `watchlist:update` permission.

### Path Parameters

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

### Request Body

<ParamField name="full_name" type="string" required>
  Full name of the subject
</ParamField>

<ParamField name="identifier" type="string">
  Document ID, wallet address, email, etc.
</ParamField>

<ParamField name="identifier_type" type="string">
  Type of identifier: `document`, `wallet`, `email`, `tax_id`, etc.
</ParamField>

<ParamField name="tags" type="array">
  Custom tags for categorization and filtering. Example: `["priority", "vip"]`
</ParamField>

<ParamField name="session_id" type="string">
  Session ID if subject was created during onboarding. Links the subject to a KYC session.
</ParamField>

### Request Example

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

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

<ParamField name="subjects" type="array" required>
  Array of subject objects to add
</ParamField>

### Request Example (Batch)

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

```json theme={null}
{
  "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](mailto:user@example.com)" |
| `tax_id`   | Tax identification number | "TAX-987654"                                  |
| `passport` | Passport number           | "AB1234567"                                   |

## Error Responses

### 400 Bad Request

```json theme={null}
{
  "status": "error",
  "error": {
    "type": "ValidationError",
    "message": "Subject must have either full_name or identifier",
    "code": "VALIDATION_ERROR"
  }
}
```

### 402 Payment Required - No Seats Available

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

```json theme={null}
{
  "status": "error",
  "error": "Not enough watchlist seats. Available: 5, Requested: 10. Please purchase more seats."
}
```

### 404 Not Found

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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="Provide Identifiers When Possible">
    While `full_name` alone is sufficient, providing identifiers improves matching accuracy:

    * More precise matches
    * Reduces false positives
    * Better audit trail
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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](/api-reference/watchlists/trigger-monitoring) to get immediate results.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Monitor Seat Usage">
    Before adding subjects, verify you have available seats. Use the [Usage API](/api-reference/usage) to check your current seat consumption and avoid 402 errors.
  </Accordion>
</AccordionGroup>

## Next Steps

* [Remove subjects](/api-reference/watchlists/remove-subject) when no longer needed
* [Get watchlist details](/api-reference/watchlists/get) to view all subjects
* Monitor screening results with [Usage API](/api-reference/usage)