Company Monitoring

Track changes to company data over time and receive webhook notifications when something changes.

Monitors let you track a company and get notified when its data changes. Each monitor runs on a schedule you define, checks for changes in company details and shareholder structure, and sends a webhook when something is different.

How It Works

Step	What happens
Create	You provide a company ID and a cron schedule
First check	Runs immediately, stores the initial state (no webhook sent)
Subsequent checks	Fetches fresh company report and shareholder graph, compares with stored state
Change detected	Sends a webhook to all your configured webhook endpoints

Category	What it covers
`company-details`	Legal name, registered address, registration status, officers, legal form, and other registry data
`shareholder-graph`	Direct shareholders of the company (1 level deep), including ownership percentages and shareholder details

Creating a Monitor

First, make sure you have a webhook configured to receive notifications.

curl -X POST https://api.kausate.com/v2/monitors \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
    "scheduleCron": "0 8 * * 1"
  }'

Response:

{
  "monitorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
  "companyName": "Bundesanzeiger Verlag GmbH",
  "scheduleCron": "0 8 * * 1",
  "checkCount": 0,
  "lastCheckedAt": null,
  "isActive": true,
  "createdAt": "2025-06-15T10:30:00Z",
  "apiUrl": "https://api.kausate.com/v2/monitors/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

The first check runs immediately after creation to capture the baseline state. No webhook is sent for the first check.

Cron Schedule

The scheduleCron field accepts standard 5-field cron expressions (UTC):

Expression	Meaning
`0 8 * * *`	Every day at 08:00 UTC
`0 8 * * 1`	Every Monday at 08:00 UTC
`0 0 1 * *`	First day of each month
`0 8 * * 1,4`	Monday and Thursday at 08:00 UTC

Webhook Notifications

When a monitor detects changes, Kausate sends a POST request to each of your webhook endpoints:

{
  "event": "monitor.change_detected",
  "monitor_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "kausate_id": "co_de_7KGHtucR88u2omSx3KhaoH",
  "changed_categories": ["company-details"],
  "timestamp": "2025-06-22T08:00:15Z",
  "api_url": "https://api.kausate.com/v2/monitors/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Field	Description
`event`	Always `monitor.change_detected`
`monitor_id`	The monitor that triggered the notification
`kausate_id`	The company being monitored
`changed_categories`	Which data changed: `company-details`, `shareholder-graph`, or both
`timestamp`	When the change was detected (ISO 8601)
`api_url`	Direct link to fetch the full monitor details including old and new state

Use the api_url to fetch the monitor details and inspect what changed.

Retry policy:

Setting	Value
Maximum attempts	50
Initial interval	1 second
Maximum interval	4 hours
Backoff multiplier	2x

If your endpoint is temporarily unreachable, Kausate keeps retrying with exponential backoff.

Inspecting Changes

To see what changed, fetch the monitor details:

curl https://api.kausate.com/v2/monitors/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: your_api_key"

The response includes oldState and newState — the full company data before and after the detected change. Compare these to identify exactly what changed.

{
  "monitorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "kausateId": "co_de_7KGHtucR88u2omSx3KhaoH",
  "companyName": "Bundesanzeiger Verlag GmbH",
  "checkCount": 5,
  "lastCheckedAt": "2025-06-22T08:00:15Z",
  "currentStateSummary": {
    "hasCompanyDetails": true,
    "hasShareholderGraph": true,
    "lastUpdated": "2025-06-22T08:00:15Z"
  },
  "oldState": { "..." },
  "newState": { "..." }
}

Field	Description
`currentStateSummary`	Quick overview of what data the monitor is tracking
`oldState`	Company data from before the last detected change
`newState`	Current company data (what triggered the change notification)

Credits

Each scheduled check consumes credits, regardless of whether changes are detected. The check fetches a fresh company report and shareholder graph from the source registry.

Managing Monitors

List all monitors:

curl https://api.kausate.com/v2/monitors \
  -H "X-API-Key: your_api_key"

Delete a monitor:

curl -X DELETE https://api.kausate.com/v2/monitors/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: your_api_key"

Deleting a monitor cancels all future scheduled checks immediately.