How to configure watchlist alerts

The /api/v1/watchlist/alerts endpoint controls when and how you receive notifications for changes detected in your company monitor: GET reads the settings, PATCH changes them. You have one global profile for all monitored companies and can give selected companies their own settings.

Before you start – defaults

Every account has a global alert profile that starts with alerts disabled (alerts_enabled: false, notify_via_email: false, threshold warning). Every company added to the list – including one restored after removal – inherits this profile. A company with its own settings takes priority over the global profile.

Reading the settings

GET without parameters returns the global profile; with identifier_type and identifier_value – the settings in effect for that company on your list. The source field tells where they come from: global or company_override. Reading changes nothing (updated: 0).

GET /api/v1/watchlist/alerts

curl "https://api.entiway.com/api/v1/watchlist/alerts" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

curl "https://api.entiway.com/api/v1/watchlist/alerts?identifier_type=NIP&identifier_value=1234560007" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Accept: application/json"

{
  "success": true,
  "data": {
    "updated": 0,
    "settings": {
      "source":              "global",
      "alerts_enabled":      false,
      "alert_min_severity":  "warning",
      "alert_event_classes": null,
      "alert_categories":    null,
      "notify_via_email":    false
    }
  }
}

Global configuration

Omit both identifier_type and identifier_value. You change the global profile – it applies immediately to all companies without their own settings, without rewriting each of them. Only the fields in the request change. In the example below, any event at warning level or above triggers an email notification.

PATCH /api/v1/watchlist/alerts

curl -X PATCH "https://api.entiway.com/api/v1/watchlist/alerts" \
  -H "Authorization: Bearer sk_api_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_min_severity": "warning",
    "alerts_enabled":     true,
    "notify_via_email":   true
  }'

{
  "success": true,
  "data": {
    "updated": 1,
    "settings": {
      "source":              "global",
      "alerts_enabled":      true,
      "alert_min_severity":  "warning",
      "alert_event_classes": null,
      "alert_categories":    null,
      "notify_via_email":    true
    }
  }
}

Global with force – all companies return to global

Adding force: true changes the global profile and at the same time removes own settings from every company on the list – each returns to the global profile. updated = 1 (profile) + the number of companies returned. Use this when you want to enforce a uniform policy across the entire watchlist.

PATCH /api/v1/watchlist/alerts

  -d '{
    "alert_min_severity": "warning",
    "alerts_enabled":     true,
    "notify_via_email":   true,
    "force":             true
  }'

Per-company configuration

Pass identifier_type and identifier_value to target a company on your list (number as when adding: no spaces or dashes, leading zeros filled in; a company not on your list → 404). The company gets its own settings (source: company_override) – they start from the current global ones and only the fields you pass change. Future changes to the global profile no longer affect it until you return it to global (use_global_settings or force). In the example below, only risk and anomaly class events in the finance or status categories at severity high or above will trigger a notification.

PATCH /api/v1/watchlist/alerts

  -d '{
    "alert_min_severity":  "high",
    "alerts_enabled":      true,
    "notify_via_email":    true,
    "alert_event_classes": ["risk", "anomaly"],
    "alert_categories":    ["finance", "status"],
    "identifier_type":     "NIP",
    "identifier_value":    "1234560007"
  }'

Returning one company to global

use_global_settings: true with a company identifier removes its own settings – the company uses the global profile again (source: global). The global profile and other companies stay unchanged.

PATCH /api/v1/watchlist/alerts

  -d '{
    "use_global_settings": true,
    "identifier_type":     "NIP",
    "identifier_value":    "1234560007"
  }'

Parameter reference

PATCH parameters are sent as a JSON body and none of them is required on its own – only the fields you pass change. The request must contain at least one setting or use_global_settings: true; empty → 422.

Settings priority

When a change is detected, the system resolves which alert settings to apply in this order:

1. Company's own settings (source: company_override) – always applied first.
2. Global profile (source: global) – for all other companies.
3. Global profile defaults (alerts off, threshold warning) – until you change the profile.