Watchlists

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

Overview

Watchlist

A named container for members you want to monitor.

Members

Entities (companies, persons, etc.) added to a watchlist.

Events & Notifications

Changes detected on members, delivered via email, webhook, or SMS.

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

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:

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

Create a watchlist

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

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

{
  "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 & Filtering for the full reference.

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:

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:

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:

{
  "movedCount": 8,
  "skippedDuplicates": ["f6e5d4c3-b2a1-..."],
  "targetWatchListGuid": "b2c3d4e5-f6a7-..."
}

Check membership

Find which watchlists an entity belongs to:

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

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

Response:

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

Subscribe to a single event type:

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:

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

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

Response:

[
  {
    "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

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.

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.

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.

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)

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 & Filtering.

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

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:

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

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:

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:

{
  "note": "End-of-week review",
  "excludeEventIds": [99, 100]
}

Dashboard

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

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:

{
  "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

Create a watchlist

POST /watchlists with a name and optional description.

Add members

Add companies, persons, addresses, properties, or vehicles to your watchlist.

Subscribe to event types

Choose specific event types or use subscribeToAll to monitor everything.

Add notifications

Set up webhook for real-time delivery, email for digests, or SMS for alerts.

Poll or receive events

Events are recorded as members change. Poll the events endpoint or receive notifications.

Acknowledge events

Mark events as reviewed — individually, in bulk, or all at once.

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

Identifiers