How to configure watchlist alerts

The PATCH /api/v1/watchlist/alerts endpoint controls when and how you receive notifications for changes detected in your company monitor. You can configure a single global policy for all monitored companies, or fine-tune settings per company.

Before you start — defaults

Alerts are disabled by default for every watchlist entry. You must explicitly activate them. Per-company settings always take priority over the global configuration.

Global configuration

Omit both identifier_type and identifier_value. The settings apply to all watchlist entries that do not have individual (custom) settings. 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": 42 }
}

Global with force — overwrite all

Adding force: true to a global request overwrites even the companies that have custom per-company settings. It also resets has_custom_settings to false for every watchlist entry. 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 single company. This sets has_custom_settings: true for that entry — it will no longer be affected by future global updates unless force: true is used. 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":    "6842685591"
  }'

Parameter reference

All parameters are sent as a JSON body. Only alert_min_severity is required.

Settings priority

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

1. Per-company settings (has_custom_settings: true) — always applied first.
2. Global settings — applied to all other entries.
3. Default (disabled) — if no settings have been configured for an entry.