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.