Every event generated by the registry carries three metadata fields: severity, event_class, and category. Together they let you filter the event stream precisely — receiving only the signals that matter for your use case.
Severity
Severity reflects the business weight of a change — how urgently it should be acted upon. It is assigned per event type and does not change dynamically. Six levels are defined, ordered from least to most critical.
| Level | Meaning | Example events |
|---|---|---|
info |
Neutral informational change, no action required. | Fax number added or changed. |
notice |
Minor but noteworthy update — worth logging. | Phone or email added, PKD code added, local unit opened. |
warning |
Significant change — review recommended. | Company name changed, address changed, PKD removed, unit closed. |
high |
Important structural change — high attention warranted. | Owner or shareholders changed, legal form changed, bankruptcy ended, resumption of activity. |
error |
(reserved for future use) | — |
critical |
Critical event — immediate attention required. | Company suspended, company closed, bankruptcy started, NIP or REGON changed. |
Event class
The event class groups events by their nature — what kind of change occurred, regardless of which data field it affected. Use it to subscribe to a pattern of behaviour rather than individual event types.
| Class | Meaning | Example events |
|---|---|---|
change |
A value was modified — something changed. | Name, address, phone, PKD codes changed. |
risk |
A negative event indicating potential problems. | Company suspended, closed, local unit closed, bankruptcy started. |
anomaly |
An unusual or statistically improbable change. | NIP changed (COMPANY_TAX_IDENTITY_CHANGED), REGON changed (ANOMALY_REGON_CHANGE). |
growth |
A positive expansion signal — something was added. | Phone, email, website added; PKD code added; local unit opened; address added. |
recovery |
A return to normal after a negative event. | Bankruptcy ended, company resumed activity. |
initialization |
A new entity appeared in the registry for the first time. | (reserved for new-company detection) |
Category
Category describes which part of the company profile the event belongs to. It lets you scope alerts to the data domains you care about — for example, only financial changes or only contact updates.
| Category | Meaning |
|---|---|
status | Operational status — suspensions, closures, resumptions, start date changes. |
identity | Legal identity — name, legal form, entity type, NIP, REGON. |
location | Address and local units — registered address, branches. |
ownership | Ownership structure — owner (sole trader) or shareholders. |
activities | Business activities — PKD codes added, removed, or changed. |
contacts | Contact details — phone, email, fax. |
web_presence | Web presence — website URL added, changed, or removed. |
finance | Financial proceedings — bankruptcy start and end. |
How fields appear in the API response
The severity field is returned on every event object across all event endpoints — /watchlist/events, /companies/events, and /events/feed. The event_class and category are metadata from the event type dictionary — use them to configure alert filters in PATCH /watchlist/alerts.
{
"event_type": "COMPANY_BANKRUPTCY_STARTED",
"old_value": null,
"new_value": "2026-04-10",
"event_date": "2026-04-11",
"severity": "critical",
}
Practical use
The three fields are designed to be combined. In PATCH /watchlist/alerts you can set alert_min_severity, alert_event_classes, and alert_categories independently — giving you precise control over which events trigger a notification.