How to use Watchlist

Watchlist lets you monitor companies that matter to you. Add them once — the system checks for changes every day and delivers typed events for every detected difference. This guide shows you how to set up monitoring and consume events effectively.

Adding companies

Add companies by their identifier — NIP, REGON9, or KRS. You can submit up to 100 identifiers in a single request. The request is asynchronous — you receive an immediate confirmation and an email notification once all entities are ready to monitor.

POST /api/v1/companies/add

curl -X POST https://alexambros.com/api/v1/companies/add \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "NIP",
    "value": ["5270103391", "7221234567", "9876543210"]
  }'

{
  "success": true,
  "message": "Accepted for processing."
}

If a company is already in the registry database it is added instantly. If not, it goes through a full import pipeline first. Either way, you receive an email when everything is ready.

Viewing your watchlist

At any time you can view all companies on your watchlist. Each entry shows the company name, primary identifier, date added, date of the last detected event, and total event count. This endpoint is free — no credits deducted.

GET /api/v1/companies/watched

curl "https://alexambros.com/api/v1/companies/watched?page=1" \
  -H "Authorization: Bearer sk_api_xxxx"

Getting events

There are two ways to consume events from your watchlist.

GET /api/v1/watchlist/events

curl "https://alexambros.com/api/v1/watchlist/events?from_date=2026-03-01&to_date=2026-03-24" \
  -H "Authorization: Bearer sk_api_xxxx"

Event structure

Every event has the same structure — event type, old value, new value, event date, and severity. When old_value is null, the field was newly added. When new_value is null, it was removed.

{
  "primary_identifier": "543701794",
  "name":               "CAR-PRO MAX DETAILING",
  "event_type":         "COMPANY_NAME_CHANGED",
  "old_value":          "CAR-PRO DETAILING",
  "new_value":          "CAR-PRO MAX DETAILING",
  "event_date":         "2026-03-02",
  "severity":           "info"
}

Removing companies

Remove companies from your watchlist using the same identifier format as adding. Daily monitoring stops immediately. The response tells you exactly which identifiers were removed, which were not found, and which were not on your watchlist.

DELETE /api/v1/companies/watched

curl -X DELETE https://alexambros.com/api/v1/companies/watched \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name":  "NIP",
    "value": ["5270103391"]
  }'

Tip — daily routine
A typical integration polls /watchlist/events once per day with yesterday's date as from_date. This gives you a clean daily feed of all changes across your monitored companies.