Monitors & events
Watch a company for change and receive a webhook when something happens
Overview
A monitor watches one company and records an event every time something
about it changes. Each event carries an eventCode — INSOLVENCY_OPENED,
DIRECTOR_ADDED, SHAREHOLDERS_CHANGED — and a broader category such as
status, ownership, or disappeared. Every event is delivered, signed, to
the webhooks registered for your organisation as it
happens; with or without a webhook, every event stays queryable through the API.
You tell us which company to watch and which categories or event codes you care about. That is all a monitor needs.
To exercise a webhook receiver before you have a real company to watch, use the Sandbox. Its companies change on every check, so you can test payload parsing and retries on demand.
Create a monitor
1. See which event codes the company can raise
The event codes a monitor can receive depend on the company's country. Ask for a country's list by its jurisdiction code:
curl "https://api.kausate.com/v2/events/taxonomy?jurisdiction=de" \
-H "X-API-Key: your_api_key" \
-H "Kausate-Version: 2026-08-01"{
"categories": ["status", "ownership", "financial", "other"],
"eventCodes": [
{ "eventCode": "INSOLVENCY_OPENED", "category": "status" },
{
"eventCode": "INSOLVENCY_DISTRIBUTION_PUBLISHED",
"category": "financial"
},
{ "eventCode": "COMPANY_DETAILS_CHANGED", "category": "other" },
{ "eventCode": "SHAREHOLDERS_CHANGED", "category": "ownership" }
]
}You can skip this step entirely: a monitor created without filters receives every event available for its company.
2. Create the monitor
curl -X POST https://api.kausate.com/v2/monitors \
-H "X-API-Key: your_api_key" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"kausateId": "co_de_UJybUvCx7CrPyqCtsDXsS",
"categoriesFilter": ["status", "ownership"],
"metadata": { "caseId": "CASE-12345", "team": "compliance" }
}'| Field | Meaning |
|---|---|
kausateId | The company to watch |
categoriesFilter | Watch only these categories. Optional, defaults to all |
eventCodesFilter | Watch only these event codes. Optional, defaults to all |
scheduleCron | How often the company is checked. Optional, defaults to monthly — see limits |
metadata | Your own JSON object, echoed back on every event. Optional, 4 KB max |
See Create Monitor for the full schema.
Changes are reported from the second check onward.
3. Receive events
A monitor does not name a URL. Register a webhook once for your organisation — the same registration your order results use — and every monitor delivers to it:
curl -X POST https://api.kausate.com/v2/webhooks \
-H "X-API-Key: your_api_key" \
-H "Kausate-Version: 2026-08-01" \
-H "Content-Type: application/json" \
-d '{
"name": "Kausate events",
"url": "https://your-server.com/webhooks/kausate"
}'Keep the signingSecret from the response; you need it to
verify each request. Each detected change is then
POSTed to every active webhook of your organisation:
{
"event": "monitor.change_detected",
"monitor_id": "00000000-0000-4000-8000-000000000002",
"kausate_id": "co_zz_4O3wnpE5u1K5AXnkARuhp",
"event_id": "00000000-0000-4000-8000-000000000003",
"event_code": "REGISTERED_ADDRESS_CHANGED",
"category": "address",
"severity": "info",
"detected_at": "2026-11-21T14:00:00+00:00",
"before": [
{
"type": "registered",
"source": "zz-sandbox",
"original": "Dradenaustraße 33, 21129 Hamburg, Germany",
"coordinate": null,
"normalized": null,
"normalizationMode": "enrich"
}
],
"after": [
{
"type": "registered",
"source": "zz-sandbox",
"original": "Am Sandtorkai 12, 20457 Hamburg, Germany",
"coordinate": null,
"normalized": null,
"normalizationMode": "enrich"
}
],
"diff_path": "companyReport.basicInformation.addresses",
"metadata": {
"caseId": "CASE-12345",
"api_url": "https://api.kausate.com/v2/monitors/00000000-0000-4000-8000-000000000002/events/00000000-0000-4000-8000-000000000003"
}
}before and after hold the values that changed, and diff_path points at the
field inside the company report — here
companyReport.basicInformation.status.normalized. Not every event carries
data; What each event carries lists it per event
code.
Categories and event codes
Every event belongs to exactly one of seven categories:
| Category | Covers |
|---|---|
status | Company status changes (active → liquidating, insolvency proceedings) |
address | Registered or business address changes |
ownership | Shareholder or beneficial-owner changes |
financial | Share-capital changes, financial publications |
legalRepresentatives | Director and authorized-signatory changes |
other | Name, legal form, activity and other record changes |
disappeared | Company dissolved, struck off, liquidated, or no longer found |
Route on whichever level fits. Use category for broad fan-out — alert your ops
team on every disappeared event. Use eventCode when you need one specific
transition.
match payload["category"]:
case "disappeared":
ops_alert(payload)
case "ownership":
compliance_review(payload)
case "status" if "INSOLVENCY" in payload["event_code"]:
risk_team(payload)
case _:
archive(payload)Two lists of event codes
There are two lists of event codes: detailed codes carry the change, generic
codes only signal it. Which codes a company can raise depends on its country;
GET /v2/events/taxonomy?jurisdiction=…
returns a country's list.
Detailed codes say exactly what changed, and the event carries the data:
before, after and diff_path as described above.
| Event code | Category | Meaning |
|---|---|---|
NAME_CHANGED | other | Legal name changed |
LEGAL_FORM_CHANGED | other | Legal form changed (GmbH → AG, Ltd → PLC) |
REGISTERED_ADDRESS_CHANGED | address | Registered office address changed |
BUSINESS_ADDRESS_CHANGED | address | Operating address changed. Not returned by any country yet |
JURISDICTION_CHANGED | address | Registry jurisdiction changed (cross-border seat transfer). Not returned by any country yet |
COMPANY_STATUS_CHANGED | status | Status on the register changed |
REGISTRATION_DATE_CHANGED | status | A date on the register changed, including its last-changed date |
ACTIVITIES_CHANGED | other | Declared business activities changed |
SHARE_CAPITAL_CHANGED | financial | Share-capital amount changed |
VAT_REGISTRATION_CHANGED | status | VAT registration granted or cancelled |
FISCAL_INACTIVITY_CHANGED | status | Fiscal-inactivity flag set or cleared. Not returned by any country yet |
COMPANY_DISSOLVED | disappeared | Company dissolved |
COMPANY_STRUCK_OFF | disappeared | Struck off the register |
COMPANY_LIQUIDATED | disappeared | Company entered liquidation or strike-off |
COMPANY_NOT_FOUND | disappeared | Register no longer returns the company. Not returned by any country yet |
DIRECTOR_ADDED | legalRepresentatives | Director or officer appointed |
DIRECTOR_REMOVED | legalRepresentatives | Director or officer left |
DIRECTOR_ROLE_CHANGED | legalRepresentatives | An existing director's role changed |
AUTHORIZED_SIGNATORY_CHANGED | legalRepresentatives | Signatory powers changed |
UBO_ADDED | ownership | New UBO declared. Not returned by any country yet |
UBO_REMOVED | ownership | UBO removed. Not returned by any country yet |
UBO_PERCENTAGE_CHANGED | ownership | An existing UBO's stake changed. Not returned by any country yet |
SHAREHOLDER_ADDED | ownership | New shareholder |
SHAREHOLDER_REMOVED | ownership | Shareholder left |
SHAREHOLDING_PERCENTAGE_CHANGED | ownership | An existing shareholder's stake changed |
INSOLVENCY_PROTECTIVE_MEASURES | status | Protective measures ordered |
INSOLVENCY_DISMISSED_FOR_LACK_OF_ASSETS | status | Application dismissed for lack of assets |
INSOLVENCY_OPENED | status | Insolvency proceedings formally opened |
INSOLVENCY_DECISION | status | Decision issued in ongoing proceedings |
INSOLVENCY_LIFTED | status | Proceedings lifted or closed |
INSOLVENCY_DISTRIBUTION_PUBLISHED | financial | Distribution to creditors published |
INSOLVENCY_DISCHARGE_DECISION | status | Discharge decision issued |
INSOLVENCY_PLAN_SUPERVISED | status | Insolvency plan or supervised proceedings |
INSOLVENCY_OTHER | other | Insolvency publication not covered by a more specific code |
FILING_PENALTY_IMPOSED | other | Penalty for a late or missing filing published |
LIQUIDATION_CREDITOR_CALL_PUBLISHED | status | Call to creditors published in a liquidation |
SHAREHOLDER_MEETING_CONVENED | other | Shareholder meeting convened |
FINANCIAL_STATEMENT_PUBLISHED | financial | Financial statement published |
OTHER | other | Change without a more specific code |
Generic codes say that something in an area changed. Raised by a change
signal, they carry nothing more: before, after and diff_path are null.
Raised by an official publication, after carries the publication, as
What each event carries shows per country.
| Event code | Category | Meaning | Detailed codes it stands for |
|---|---|---|---|
COMPANY_DETAILS_CHANGED | other | Something on the company's register record changed | NAME_CHANGED, LEGAL_FORM_CHANGED, ACTIVITIES_CHANGED, REGISTRATION_DATE_CHANGED, OTHER |
ADDRESS_CHANGED | address | An address of the company changed | REGISTERED_ADDRESS_CHANGED, BUSINESS_ADDRESS_CHANGED, JURISDICTION_CHANGED |
STATUS_CHANGED | status | The company's status changed | COMPANY_STATUS_CHANGED, VAT_REGISTRATION_CHANGED, FISCAL_INACTIVITY_CHANGED |
CAPITAL_CHANGED | financial | The company's capital changed. Not returned by any country yet | SHARE_CAPITAL_CHANGED |
LEGAL_REPRESENTATIVES_CHANGED | legalRepresentatives | The company's legal representatives changed | DIRECTOR_ADDED, DIRECTOR_REMOVED, DIRECTOR_ROLE_CHANGED, AUTHORIZED_SIGNATORY_CHANGED |
SHAREHOLDERS_CHANGED | ownership | The company's shareholders or beneficial owners changed | SHAREHOLDER_ADDED, SHAREHOLDER_REMOVED, SHAREHOLDING_PERCENTAGE_CHANGED, UBO_ADDED, UBO_REMOVED, UBO_PERCENTAGE_CHANGED |
INSOLVENCY_NOTICE_PUBLISHED | status | An insolvency notice about the company was published | INSOLVENCY_PROTECTIVE_MEASURES, INSOLVENCY_DISMISSED_FOR_LACK_OF_ASSETS, INSOLVENCY_OPENED, INSOLVENCY_DECISION, INSOLVENCY_LIFTED, INSOLVENCY_DISTRIBUTION_PUBLISHED, INSOLVENCY_DISCHARGE_DECISION, INSOLVENCY_PLAN_SUPERVISED, INSOLVENCY_OTHER |
OFFICIAL_NOTICE_PUBLISHED | other | An official notice about the company was published | FILING_PENALTY_IMPOSED, LIQUIDATION_CREDITOR_CALL_PUBLISHED, SHAREHOLDER_MEETING_CONVENED, FINANCIAL_STATEMENT_PUBLISHED |
COMPANY_CLOSED | disappeared | The company was dissolved, struck off or is no longer found. Not returned by any country yet | COMPANY_DISSOLVED, COMPANY_STRUCK_OFF, COMPANY_LIQUIDATED, COMPANY_NOT_FOUND |
A generic event is a signal to look. When one arrives, order a fresh company report or shareholder graph for the company and compare it with what you hold:
{
"event": "monitor.change_detected",
"monitor_id": "9d2f0c6e-5b1a-4c0e-9a57-0c1f3a6a2b11",
"kausate_id": "co_de_UJybUvCx7CrPyqCtsDXsS",
"event_id": "c1c6d0a4-6d0b-4d4b-8a3f-7d0f2e7f6a10",
"event_code": "SHAREHOLDERS_CHANGED",
"category": "ownership",
"severity": "info",
"detected_at": "2026-10-01T00:04:12.118430+00:00",
"diff_path": null,
"before": null,
"after": null,
"metadata": {
"caseId": "CASE-12345",
"api_url": "https://api.kausate.com/v2/monitors/9d2f0c6e-5b1a-4c0e-9a57-0c1f3a6a2b11/events/c1c6d0a4-6d0b-4d4b-8a3f-7d0f2e7f6a10"
}
}Both lists are valid in eventCodesFilter:
- A generic code works everywhere it has something to stand for. In a country
that returns detailed codes, filtering on
SHAREHOLDERS_CHANGEDdeliversSHAREHOLDER_ADDED,SHAREHOLDER_REMOVEDand the other detailed codes it stands for — so one filter can serve companies in several countries. - A code the company's country never returns is rejected with a
422naming the code, rather than creating a monitor that can never fire. The same applies to filters that together leave nothing to watch.
An event's category is the category of its own code. A generic code and a
detailed code it stands for can sit in different categories —
INSOLVENCY_DISTRIBUTION_PUBLISHED is financial, INSOLVENCY_NOTICE_PUBLISHED
is status — so check the tables above when you route on category.
Rather than copying the tables, fetch the list from
GET /v2/events/taxonomy at startup
and build your routing table from the response. Without a jurisdiction it
returns every code; codes added in later releases are then picked up
automatically.
What each event carries
Every event carries the change in three fields: diff_path says what changed,
before holds it as it was, and after as it is now. What they hold depends on
how the event was raised:
- A field of the company report or shareholder graph changed.
diff_pathis the field's path, andbeforeandafterhold its value, typed as in Company report and Shareholder graph. - An entry of a list was added, removed or changed — a representative, a
shareholder, an ownership link. Each entry is its own event, and
diff_pathnames it, as incompanyReport.relationships.legalRepresentatives[name='Jane Doe'].afterholds the entry that was added,beforethe one that was removed, and both are set when it changed. When several entries share a name,beforeandafterhold the list of those entries. Entries without a name are compared together as one event atcompanyReport.relationships.legalRepresentatives[name=<unidentified>], andbeforeandafterhold them as{"__items__": [ … ]}. - An official publication — an insolvency notice, a gazette announcement.
The publication itself is the change, so
beforeanddiff_patharenullandaftercarries the full publication as the register published it. Its fields differ from country to country. - A change signal. The event says that something changed and nothing more:
before,afteranddiff_patharenull. Order a fresh report or shareholder graph to see what.
Detailed codes
| Event code | Raised by | diff_path | before | after |
|---|---|---|---|---|
NAME_CHANGED | Company report | companyReport.basicInformation.legalName | string | string |
NAME_CHANGED | Official publication, in ca-ab, nz | null | null | The publication |
LEGAL_FORM_CHANGED | Company report | companyReport.basicInformation.legalForm.normalized | string | string |
REGISTERED_ADDRESS_CHANGED | Company report | companyReport.basicInformation.addresses | Address[] | Address[] |
COMPANY_STATUS_CHANGED | Company report | companyReport.basicInformation.status.normalized | CompanyStatusType | CompanyStatusType |
COMPANY_STATUS_CHANGED | Official publication, in ca-ab, nz | null | null | The publication |
REGISTRATION_DATE_CHANGED | Company report | companyReport.basicInformation.dates | Dates | Dates |
ACTIVITIES_CHANGED | Company report | companyReport.basicInformation.activities | Activity[] | Activity[] |
ACTIVITIES_CHANGED | Official publication, in nz | null | null | The publication |
SHARE_CAPITAL_CHANGED | Company report | companyReport.basicInformation.capital | Capital | Capital |
VAT_REGISTRATION_CHANGED | Official publication, in nz | null | null | The publication |
COMPANY_DISSOLVED | Company report | companyReport.basicInformation.status.normalized | CompanyStatusType | CompanyStatusType |
COMPANY_STRUCK_OFF | Company report | companyReport.basicInformation.status.normalized | CompanyStatusType | CompanyStatusType |
COMPANY_STRUCK_OFF | Official publication, in ca-ab | null | null | The publication |
COMPANY_LIQUIDATED | Company report | companyReport.basicInformation.status.normalized | CompanyStatusType | CompanyStatusType |
DIRECTOR_ADDED | Company report | companyReport.relationships.legalRepresentatives[name=…] | null | LegalRepresentative |
DIRECTOR_REMOVED | Company report | companyReport.relationships.legalRepresentatives[name=…] | LegalRepresentative | null |
DIRECTOR_ROLE_CHANGED | Company report | companyReport.relationships.legalRepresentatives[name=…] | LegalRepresentative | LegalRepresentative |
AUTHORIZED_SIGNATORY_CHANGED | Company report, only when the list cannot be compared entry by entry, which no published company report causes | companyReport.relationships.legalRepresentatives | The whole list | The whole list |
SHAREHOLDER_ADDED | Shareholder graph | graph.nodes[id=…] | null | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode |
SHAREHOLDER_ADDED | Shareholder graph | graph.edges[id=…] | null | ShareholderEdge |
SHAREHOLDER_REMOVED | Shareholder graph | graph.nodes[id=…] | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode | null |
SHAREHOLDER_REMOVED | Shareholder graph | graph.edges[id=…] | ShareholderEdge | null |
SHAREHOLDING_PERCENTAGE_CHANGED | Shareholder graph | graph.nodes[id=…] | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode | CompanyNode | PersonNode | RootEntityNode | FreeFloatNode | UnknownNode |
SHAREHOLDING_PERCENTAGE_CHANGED | Shareholder graph | graph.edges[id=…] | ShareholderEdge | ShareholderEdge |
INSOLVENCY_PROTECTIVE_MEASURES | Official publication, in at, cz, de, es, pl | null | null | The publication |
INSOLVENCY_DISMISSED_FOR_LACK_OF_ASSETS | Official publication, in at, cz, de, pl | null | null | The publication |
INSOLVENCY_OPENED | Official publication, in at, cz, de, es, pl | null | null | The publication |
INSOLVENCY_DECISION | Official publication, in at, cz, de, es, pl | null | null | The publication |
INSOLVENCY_LIFTED | Official publication, in at, cz, de, es, pl | null | null | The publication |
INSOLVENCY_DISTRIBUTION_PUBLISHED | Official publication, in at, cz, de, es, pl | null | null | The publication |
INSOLVENCY_DISCHARGE_DECISION | Official publication, in at, cz, de, es, pl | null | null | The publication |
INSOLVENCY_PLAN_SUPERVISED | Official publication, in at, cz, de, es, pl | null | null | The publication |
INSOLVENCY_OTHER | Official publication, in at, cz, de, es, pl | null | null | The publication |
FILING_PENALTY_IMPOSED | Official publication, in at | null | null | The publication |
LIQUIDATION_CREDITOR_CALL_PUBLISHED | Official publication, in at | null | null | The publication |
SHAREHOLDER_MEETING_CONVENED | Official publication, in at | null | null | The publication |
FINANCIAL_STATEMENT_PUBLISHED | Official publication, in at | null | null | The publication |
OTHER | Company report, in zz | companyReport.sources.zz-sandbox.retrievalTime | string | string |
OTHER | Official publication, in at, ca-ab, cz, de, es, nz, pl | null | null | The publication |
Generic codes
| Event code | Raised by | diff_path | before | after |
|---|---|---|---|---|
COMPANY_DETAILS_CHANGED | Official publication, in nz | null | null | The publication |
COMPANY_DETAILS_CHANGED | Change signal, in de | null | null | null |
ADDRESS_CHANGED | Official publication, in nz | null | null | The publication |
STATUS_CHANGED | Official publication, in nz | null | null | The publication |
LEGAL_REPRESENTATIVES_CHANGED | Official publication, in nz | null | null | The publication |
SHAREHOLDERS_CHANGED | Official publication, in nz | null | null | The publication |
SHAREHOLDERS_CHANGED | Change signal, in de | null | null | null |
INSOLVENCY_NOTICE_PUBLISHED | Official publication, in nz | null | null | The publication |
OFFICIAL_NOTICE_PUBLISHED | Official publication, in nz | null | null | The publication |
A value is compared as published: a date written differently, or an amount
with more trailing zeros, is not a change. before and after still hold the
values as written.
Examples
What diff_path, before and after hold for each code raised by a change to
the company report or shareholder graph:
Filtering deliveries
categoriesFilter and eventCodesFilter decide what a monitor watches and what
reaches your webhook. Set both and an event must satisfy each independently to be
delivered.
Filters are not a knob you can widen later: a monitor's filters are fixed when it is created, and neither filter backfills. An event your filters exclude may not be recorded at all, so it cannot be recovered afterwards. If you might want a category later, subscribe to it now and discard it on your side.
Correlating events with your own records
The optional metadata object you set on a monitor is echoed back on every event
it produces:
"metadata": { "caseId": "CASE-12345", "team": "compliance" }It comes back verbatim on monitor responses, and merged into each event's
metadata alongside Kausate's own annotations — external_id and publication
details on events raised by an official publication, and api_url on webhook
deliveries. Kausate's keys win on a name collision, so avoid external_id,
jurisdiction, api_url and any key starting with native_ if you need your
own values back unchanged. The object must be JSON and 4 KB or smaller.
Webhook delivery
Monitor events go to the webhooks registered for your
organisation — every active one receives every event
your monitors deliver. There is one set of endpoints for everything Kausate
sends you: add, change, pause or remove an endpoint through
/v2/webhooks or the dashboard, and
every monitor follows without being touched. An organisation with no active
webhook is sent nothing; its events are still recorded and queryable.
Each event is delivered at least once, signed with the receiving endpoint's
secret, and retried with backoff when your endpoint fails.
Receive webhooks builds the endpoint: verifying the
signature, answering in time, deduplicating on Kausate-Webhook-Id, the
retry schedule, and recovering what it missed.
Event history and replay
Every event a monitor records is queryable. This is how you recover after an outage, pick up events of a code your webhook handler ignored, or rebuild a downstream system from history.
# Filter by eventCode, category, since, and until
curl "https://api.kausate.com/v2/monitors/$MONITOR_ID/events?limit=100&category=status&since=2026-05-01T00:00:00Z" \
-H "X-API-Key: your_api_key" \
-H "Kausate-Version: 2026-08-01"Each event includes a deliveries array with the status, target,
deliveredAt and lastError of each delivery — one entry per endpoint the
event was sent to.
Re-send a single event with
POST /v2/monitors/{id}/events/{eventId}/replay,
which returns 202 {"status":"queued"}:
curl -X POST "https://api.kausate.com/v2/monitors/$MONITOR_ID/events/$EVENT_ID/replay" \
-H "X-API-Key: your_api_key" \
-H "Kausate-Version: 2026-08-01"A replay sends the event to every webhook that is active when you replay it,
with a new Kausate-Webhook-Id and the original event_id. There is no bulk replay; re-send many events
one at a time.
Choosing a schedule
scheduleCron is a five-field cron expression, in UTC, for how often the
company is checked. It has limits:
- A monitor may be checked at most once a month and must be checked at
least once a year.
0 0 1 * *(monthly, the default),0 6 15 */3 *(quarterly) and0 0 1 1 *(yearly) are accepted; a weekly or daily expression is rejected with a422. - Sandbox companies may be checked as often as hourly.
- If you need a company checked more often than monthly, contact support — the limit can be raised for your organisation.
Each check consumes credits whether or not it finds a change, including a monitor that only watches official publications. Delivering events is included: an event costs nothing extra, however many webhooks receive it. In some countries a check also fetches a company report or shareholder graph: in France, Germany, Spain, Estonia and the United Kingdom that is included in the check, and elsewhere it is charged at its usual price. A check that fails is not charged. A monitor keeps checking until you delete it, so delete monitors you no longer need — including those of dissolved companies.
Events from official publications, such as insolvency notices, do not follow the schedule: expect one within about a day of the publication.
Troubleshooting
My webhook is not firing
- Is a webhook registered and active? List them with
GET /v2/webhooks. Without one, events are recorded but sent nowhere. - Was the event recorded? List the monitor's events with
sinceset to your last known delivery. If the event is there, it was detected, and the problem is filtering or delivery. - Do your filters allow it?
GET /v2/monitors/{id}returnscategoriesFilterandeventCodesFilter. An event that fails either is never delivered. - Is your endpoint healthy? Replay the event and watch your server logs for the new attempt. Any non-2xx response, or one slower than the request timeout, counts as a failure — and so does rejecting a request whose signature you checked with the wrong endpoint's secret.
- Still failing after a replay? The problem is on your side — DNS, TLS,
firewall, or a slow handler. The
deliveriesarray on the event carrieslastErrorfrom the last attempt.
I am receiving the same event twice
Expected — delivery is at least once. See Deduplicate on the webhook ID.
An address change fired but the address looks the same
Treat the event as a prompt to re-read the company report.
A publication event matched the wrong company
Check metadata.external_id and the publication in after, and contact
support if it keeps happening.
before and after are null
Expected for an event raised by a change signal: it says that something
changed, and you order a fresh report or shareholder graph to see what.
before alone is null on an event raised by an official publication, and on
a list entry that was added — there is no previous state. See
What each event carries.
I expected an event after creating the monitor
Changes are reported from the second check onward, so with the monthly default the first event can be a month away.
Limitations
- Not every code is returned everywhere. A country's page lists the codes it returns, and the tables above mark the codes no country returns yet. Handle a code you did not expect defensively, but do not build a feature on a code your companies' countries do not list.
- A monitor cannot be edited. Filters and schedule are set at creation. Create a new monitor and delete the old one to change them.
- Webhooks are per organisation, not per monitor. Every active webhook
receives the events of every monitor; route on
monitor_id,kausate_idor your ownmetadatain the receiver. - Replay is one event at a time. There is no bulk replay endpoint.
Common errors
Branch on the code field of the error body — never on the wording of
detail. See the Errors guide for the body shape and the
prefix-matching contract.
| Status | code | Reason | Fix |
|---|---|---|---|
404 | resource.not_found | The kausateId, monitor or event doesn't exist | Find the company first via /v2/companies/search/autocomplete, or re-list your monitors |
422 | request.invalid | The request body is well-formed but unusable: an event code that is not available for the company, filters that leave nothing to watch, or a scheduleCron that is invalid or outside the limits | Read detail for which one; list a country's codes via /v2/events/taxonomy?jurisdiction=…, and see limits |
422 covers every request-shape failure, so code alone does not distinguish
the causes — detail names the offending value. Everything above is
client-fixable; nothing here should be retried unchanged.
Last updated on