Watchlists

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

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 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
18	`CompanyGroup`	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
57	`ResidentMovedIn`	Address
58	`ResidentMovedOut`	Address

CompanyGroup reports a change in the company’s corporate group: it joined or left a group, or its parent or ultimate parent changed. A change further up the group that leaves both of them as they were does not count.

ResidentMovedIn and ResidentMovedOut report that someone has registered as living at a watched address, or has moved away from it or been deregistered. A move between apartments at the same address does not count. The events carry no personal data, and people with protected personal data never produce them.

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}

Test a webhook notification

POST /watchlists/{watchlistGuid}/notifications/{notificationId}/test

Sends one sample event to the webhook and returns the payload. See Webhooks & notifications for the payload format.

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.

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

Overview

Minimum plan

Watchlist CRUD

List watchlists

Create a watchlist

Update a watchlist

Delete a watchlist

Members

Adding a member

Listing members (paginated)

Exporting members

Removing a member

Moving members

Check membership

Event subscriptions

List subscriptions

Subscribe to event types

Unsubscribe

Event types

Notifications

List notifications

Create a notification

Delete a notification

Test a webhook notification

Events

List events (paginated)

Export events

Acknowledge a single event

Unacknowledge a single event

Bulk acknowledge

Bulk unacknowledge

Acknowledge all

Dashboard

Typical workflow

Error reference