> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Watchlists

> Monitor companies, persons, addresses, properties, and vehicles with LENS watchlists. Receive events via webhook, email, or SMS when subscribed changes occur.

Watchlists let you group companies, persons, addresses, properties, and vehicles into named lists and receive notifications when monitored entities change.

## Overview

| Concept           | Meaning                                                                                 |
| ----------------- | --------------------------------------------------------------------------------------- |
| **Watchlist**     | A named container for members you want to monitor.                                      |
| **Members**       | Entities (companies, persons, addresses, properties, vehicles) added to a watchlist.    |
| **Subscriptions** | Event types the watchlist is tracking — without a subscription, no events are recorded. |
| **Notifications** | Destinations (webhook / email / SMS) that receive events for a watchlist.               |
| **Events**        | Changes detected on members, delivered to every enabled notification.                   |

## Minimum plan

| Member type | Minimum plan    |
| ----------- | --------------- |
| Companies   | **Pro+**        |
| Vehicles    | **Pro+**        |
| Persons     | **Max+**        |
| Addresses   | **Enterprise+** |
| Properties  | **Enterprise+** |

Watchlist management, notifications, subscriptions, and events are available on **Pro+**.

## Watchlist CRUD

### List watchlists

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://lens-api.tic.io/watchlists?sortBy=name"
```

Query parameters:

| Parameter | Type   | Default | Description         |
| --------- | ------ | ------- | ------------------- |
| `sortBy`  | string | `name`  | `name` or `created` |

Response — array of watchlist objects:

```json theme={null}
[
  {
    "watchListGuid": "a1b2c3d4-e5f6-...",
    "watchListName": "My companies",
    "watchListDescription": "Portfolio monitoring",
    "numberOfCompanies": 42,
    "numberOfPersons": 0,
    "numberOfNotifications": 2,
    "numberOfSubscriptions": 5,
    "numberOfUnacknowledgedEvents": 3
  }
]
```

### Create a watchlist

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "watchListName": "My companies", "watchListDescription": "Portfolio monitoring" }'
```

| Field                  | Type   | Required | Constraints         |
| ---------------------- | ------ | -------- | ------------------- |
| `watchListName`        | string | Yes      | 1–200 characters    |
| `watchListDescription` | string | No       | Max 1000 characters |

Returns `201 Created` with the full watchlist object and a `Location` header.

### Update a watchlist

```
PUT /watchlists/{watchlistGuid}
```

Same request body as create. Returns the updated watchlist.

### Delete a watchlist

```
DELETE /watchlists/{watchlistGuid}
```

Returns `204 No Content`. Deleting a watchlist removes all members, events, notifications, and subscriptions.

## Members

Each member type has the same three operations: **list** (paginated), **add**, and **remove**.

### Adding a member

```bash theme={null}
# Add a company
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/companies/3508351" \
  -H "x-api-key: YOUR_API_KEY"
```

Replace `companies/3508351` with the entity type and ID:

| Entity   | Route                      | ID field     |
| -------- | -------------------------- | ------------ |
| Company  | `/companies/{companyId}`   | `companyId`  |
| Person   | `/persons/{personId}`      | `personId`   |
| Address  | `/addresses/{addressId}`   | `addressId`  |
| Property | `/properties/{propertyId}` | `propertyId` |
| Vehicle  | `/vehicles/{vehicleId}`    | `vehicleId`  |

Returns `201 Created` with the member GUID:

```json theme={null}
{
  "watchListMemberGuid": "f6e5d4c3-b2a1-...",
  "companyId": 3508351
}
```

Returns `409 Conflict` if the entity is already a member.

### Listing members (paginated)

Member lists use the same offset-based pagination as other table endpoints. See [Pagination](/api-lens/pagination) for the full reference.

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/companies" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "startRow": 0, "endRow": 50 }'
```

Paginated member endpoints:

| Endpoint                           | Description      |
| ---------------------------------- | ---------------- |
| `POST /watchlists/{id}/companies`  | Company members  |
| `POST /watchlists/{id}/persons`    | Person members   |
| `POST /watchlists/{id}/addresses`  | Address members  |
| `POST /watchlists/{id}/properties` | Property members |
| `POST /watchlists/{id}/vehicles`   | Vehicle members  |

### Exporting members

Each member type can be exported as CSV:

```
GET /watchlists/{watchlistGuid}/companies/export
GET /watchlists/{watchlistGuid}/persons/export
GET /watchlists/{watchlistGuid}/addresses/export
GET /watchlists/{watchlistGuid}/properties/export
GET /watchlists/{watchlistGuid}/vehicles/export
```

### Removing a member

```
DELETE /watchlists/{watchlistGuid}/members/{memberGuid}
```

Returns `204 No Content`. Associated events are also deleted.

### Moving members

Move a single member to another watchlist:

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/members/{memberGuid}/move" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targetWatchListGuid": "b2c3d4e5-f6a7-..." }'
```

Move multiple members at once:

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/members/move" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetWatchListGuid": "b2c3d4e5-f6a7-...",
    "memberGuids": ["f6e5d4c3-b2a1-...", "a1b2c3d4-e5f6-..."]
  }'
```

Returns `409` for members that already exist in the target watchlist. Bulk move reports skipped duplicates:

```json theme={null}
{
  "movedCount": 8,
  "skippedDuplicates": ["f6e5d4c3-b2a1-..."],
  "targetWatchListGuid": "b2c3d4e5-f6a7-..."
}
```

### Check membership

Find which watchlists an entity belongs to:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://lens-api.tic.io/watchlists/membership?companyId=3508351"
```

Pass exactly one query parameter: `companyId`, `personId`, `addressId`, `propertyId`, or `vehicleId`.

## Event subscriptions

Subscriptions control **which event types** generate events for a watchlist. Without subscriptions, no events are recorded.

### List subscriptions

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://lens-api.tic.io/watchlists/{watchlistGuid}/subscriptions"
```

Response:

```json theme={null}
[
  {
    "subscriptionId": "abcdef01-2345-...",
    "eventType": 1,
    "eventTypeName": "CompanyAddress",
    "lastUpdatedAtUtc": "2025-03-15T10:30:00Z"
  }
]
```

### Subscribe to event types

Subscribe to a single event type:

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/subscriptions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventType": 1 }'
```

Subscribe to all event types at once:

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/subscriptions" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "subscribeToAll": true }'
```

### Unsubscribe

```
DELETE /watchlists/{watchlistGuid}/subscriptions/{subscriptionId}
```

### Event types

| Value | Name                         | Entity   |
| ----- | ---------------------------- | -------- |
| 1     | `CompanyAddress`             | Company  |
| 2     | `CompanyName`                | Company  |
| 3     | `CompanyStatus`              | Company  |
| 4     | `CompanyRegistration`        | Company  |
| 5     | `CompanyIntelligence`        | Company  |
| 6     | `CompanyBeneficialOwner`     | Company  |
| 7     | `CompanyDocument`            | Company  |
| 8     | `CompanyWorkplace`           | Company  |
| 9     | `CompanyPerson`              | Company  |
| 10    | `CompanyRegisteredOffice`    | Company  |
| 11    | `CompanyShareCapital`        | Company  |
| 12    | `CompanyPurpose`             | Company  |
| 13    | `CompanyDebtBalance`         | Company  |
| 14    | `CompanyOrderToPayCase`      | Company  |
| 15    | `CompanyFinancialDocument`   | Company  |
| 16    | `CompanyCase`                | Company  |
| 17    | `CompanyWorkplaceAddress`    | Company  |
| 25    | `PersonAddress`              | Person   |
| 26    | `PersonName`                 | Person   |
| 27    | `PersonIntelligence`         | Person   |
| 28    | `PersonStatus`               | Person   |
| 29    | `PersonCompany`              | Person   |
| 40    | `PropertyOwnershipChange`    | Property |
| 41    | `PropertyMortgageDeedChange` | Property |
| 47    | `VehicleOwnerChange`         | Vehicle  |
| 48    | `VehicleUserChange`          | Vehicle  |
| 49    | `VehicleStatusChange`        | Vehicle  |
| 50    | `VehicleInspection`          | Vehicle  |
| 51    | `VehicleStolen`              | Vehicle  |

## Notifications

Notifications define **where** events are delivered. Each watchlist can have multiple notification destinations.

### List notifications

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://lens-api.tic.io/watchlists/{watchlistGuid}/notifications"
```

Response:

```json theme={null}
[
  {
    "notificationId": "12345678-abcd-...",
    "destination": "https://example.com/webhook",
    "destinationType": 0,
    "destinationTypeDescription": "Webhook",
    "hasBeenValidated": true,
    "lastUpdatedAtUtc": "2025-03-15T10:30:00Z"
  }
]
```

### Create a notification

| Field             | Type   | Description                                       |
| ----------------- | ------ | ------------------------------------------------- |
| `destination`     | string | Email address, webhook URL, or E.164 phone number |
| `destinationType` | int    | `0` = Webhook, `1` = Email, `2` = SMS             |

<Tabs>
  <Tab title="Webhook">
    ```bash theme={null}
    curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/notifications" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "destination": "https://example.com/webhook", "destinationType": 0 }'
    ```

    Destination must be a valid `https://` URL.
  </Tab>

  <Tab title="Email">
    ```bash theme={null}
    curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/notifications" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "destination": "alerts@example.com", "destinationType": 1 }'
    ```

    Destination must be a valid email address.
  </Tab>

  <Tab title="SMS">
    ```bash theme={null}
    curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/notifications" \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "destination": "+46701234567", "destinationType": 2 }'
    ```

    Destination must be a valid E.164 mobile phone number.
  </Tab>
</Tabs>

Returns `409 Conflict` if the destination already exists on the watchlist.

### Delete a notification

```
DELETE /watchlists/{watchlistGuid}/notifications/{notificationId}
```

## Events

When a subscribed change is detected on a member, an event is recorded. Events persist until the member is removed.

### List events (paginated)

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/events" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "startRow": 0, "endRow": 50 }'
```

Uses offset-based pagination. See [Pagination](/api-lens/pagination).

Each event contains:

| Field                                                               | Type     | Description                             |
| ------------------------------------------------------------------- | -------- | --------------------------------------- |
| `eventId`                                                           | int      | Unique event identifier                 |
| `watchListMemberGuid`                                               | Guid     | The member that changed                 |
| `eventType`                                                         | int      | Event type (see table above)            |
| `subType`                                                           | string   | Additional detail about the change      |
| `eventDate`                                                         | datetime | When the change was detected            |
| `isAcknowledged`                                                    | bool     | Whether the event has been acknowledged |
| `acknowledgedNote`                                                  | string   | Note added during acknowledgement       |
| `companyId` / `personId` / `addressId` / `propertyId` / `vehicleId` | int      | The entity that changed (one is set)    |

### Export events

```
GET /watchlists/{watchlistGuid}/events/export
```

Returns a CSV file.

### Acknowledge a single event

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/events/42/acknowledge" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "Reviewed, no action needed" }'
```

The `note` field is optional.

### Unacknowledge a single event

```
DELETE /watchlists/{watchlistGuid}/events/{eventId}/acknowledge
```

### Bulk acknowledge

Acknowledge multiple events at once:

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/events/acknowledge" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventIds": [42, 43, 44], "note": "Batch reviewed" }'
```

### Bulk unacknowledge

```bash theme={null}
curl -X DELETE "https://lens-api.tic.io/watchlists/{watchlistGuid}/events/acknowledge" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "eventIds": [42, 43, 44] }'
```

### Acknowledge all

Acknowledge every unacknowledged event on a watchlist:

```bash theme={null}
curl -X POST "https://lens-api.tic.io/watchlists/{watchlistGuid}/events/acknowledge-all" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": "End-of-week review" }'
```

Optionally exclude specific events:

```json theme={null}
{
  "note": "End-of-week review",
  "excludeEventIds": [99, 100]
}
```

## Dashboard

Get a summary of a watchlist including recent events and event counts per entity type:

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" \
  "https://lens-api.tic.io/watchlists/{watchlistGuid}/dashboard?recentEventCount=10"
```

| Parameter          | Type | Default | Max |
| ------------------ | ---- | ------- | --- |
| `recentEventCount` | int  | 10      | 25  |

Response:

```json theme={null}
{
  "watchListGuid": "a1b2c3d4-e5f6-...",
  "watchListName": "My companies",
  "totalMembers": 42,
  "unacknowledgedEventCount": 3,
  "lastEventAtUtc": "2025-03-15T10:30:00Z",
  "eventBreakdown": {
    "companyEvents": 12,
    "personEvents": 0,
    "addressEvents": 0,
    "propertyEvents": 0,
    "vehicleEvents": 0,
    "totalEvents": 12
  },
  "recentEvents": [
    {
      "eventId": 42,
      "memberGuid": "f6e5d4c3-b2a1-...",
      "eventType": 2,
      "subType": "Name changed",
      "eventDate": "2025-03-15T10:30:00Z",
      "isAcknowledged": false,
      "entityType": "Company",
      "entityName": "Volvo AB",
      "entityId": 3508351
    }
  ]
}
```

## Typical workflow

<Steps>
  <Step title="Create a watchlist">
    `POST /watchlists` with a name and optional description.
  </Step>

  <Step title="Add members">
    Add companies, persons, addresses, properties, or vehicles to your watchlist.
  </Step>

  <Step title="Subscribe to event types">
    Choose specific event types or use `subscribeToAll` to monitor everything.
  </Step>

  <Step title="Add notifications">
    Set up webhook for real-time delivery, email for digests, or SMS for alerts.
  </Step>

  <Step title="Poll or receive events">
    Events are recorded as members change. Poll the events endpoint or receive notifications.
  </Step>

  <Step title="Acknowledge events">
    Mark events as reviewed — individually, in bulk, or all at once.
  </Step>
</Steps>

## Error reference

| Status | Cause                                          |
| ------ | ---------------------------------------------- |
| `201`  | Member or resource created                     |
| `204`  | Delete successful                              |
| `400`  | Invalid request body or missing required field |
| `404`  | Watchlist or member not found                  |
| `409`  | Duplicate member or notification               |