Monitors

Monitors are the tax numbers we notify you about whenever they change in the FURS lists. Notifications go out by e-mail and to your webhooks. Monitors are available from the Starter plan. Managing the list is free (0 units); the number of slots depends on the plan: Starter 50, Growth 500, Custom by contract. Keys need the monitors scope (new keys have it by default); the org has one list, shared by all its keys and the dashboard.

The Hobby plan includes no monitors: adding one (POST /v1/monitors or add in /v1/monitors/bulk) returns 403 plan_upgrade_required, so Hobby gets no e-mail alerts either. Listing (GET) and removing work on every plan. Every change of your monitors is also listed in the dashboard (Changes page).

curl -X POST https://api.maticna.si/v1/monitors -H "Authorization: Bearer $MATICNA_KEY" \
  -H "Content-Type: application/json" -d '{"tax_number": "SI19000013", "label": "Supplier 123"}'
curl "https://api.maticna.si/v1/monitors?limit=100" -H "Authorization: Bearer $MATICNA_KEY"
curl -X DELETE https://api.maticna.si/v1/monitors/19000013 -H "Authorization: Bearer $MATICNA_KEY"
curl -X POST https://api.maticna.si/v1/monitors/bulk -H "Authorization: Bearer $MATICNA_KEY" \
  -H "Content-Type: application/json" -d '{"add": ["19000013"], "remove": ["19000021"]}'

• POST returns 201 (added) or 200 (already monitored). Any well-formed tax number is accepted, even one not yet in the FURS lists (you then receive entity.created). The response carries no taxpayer data.
• Full slots return 403 monitor_limit_reached; on Hobby, adding returns 403 plan_upgrade_required. The list response has slots: {used, limit} and a next_cursor.
• Bulk takes up to 1,000 tax numbers in add + remove; removals run first, additions are all-or-nothing against the slots. Each item gets a result: added, exists, removed, not_monitored or invalid.

E-mail alerts

In the dashboard (Watchlist → E-mail alerts) you choose how we tell you about changes of your monitors:

• Right after each data refresh: one e-mail per organization for every FURS data refresh (usually once per working day) listing every change. On by default.
• Weekly summary: on Monday morning (Slovenian time), a summary of the past week, Monday to Sunday. Weeks without changes send nothing.
• Change types: only the types you pick (e.g. VAT ID revoked, deregistered); none picked means all.

Recipients are organization members with a verified e-mail address. Owners and admins receive alerts by default, other members opt in themselves; each also picks the language (Slovenian or English). Every e-mail has a one-click unsubscribe link (and a List-Unsubscribe header) and a link to the Changes page.

The rules match webhooks: only changes detected after you added the monitor; hidden entities without names or values; sole-trader data counts against your plan’s daily natural-person cap (masked above it). After a downgrade we alert only on as many of your oldest monitors as the plan has slots; after a move to Hobby they stay on the list (you can remove them), but we send no alerts for them. At most 12 instant e-mails per organization in 24 hours and 100 changes per e-mail (the rest are in the dashboard).