Company Monitoring

Supported Countries for Monitoring

Monitoring is available in many countries. See the full list and live coverage at topograph.co/pricing.

Monitoring availability and commercial terms are account-specific. Use the pricing page and dashboard for the current source of truth before enabling monitoring at scale.

What is Monitoring?

Topograph provides automated, continuous tracking of company data in official registers in the supported countries. We detect meaningful changes using AI, categorize them intelligently, and deliver real-time webhook notifications when something important happened. Think of it as a watchdog for public company data that:

Checks daily for changes in the register for monitored companies
Uses AI to understand what changed and whether it matters
Notifies you instantly when significant changes occur
Auto-deactivates when companies cease to exist

Core Concepts

Monitor

A Monitor tracks a specific company in a specific country for changes. When you create a monitor, you’ll receive notifications whenever significant changes occur in that company’s data.

Change Categories

The AI categorizes detected changes into 7 distinct types to help you route and prioritize notifications:

status - Legal lifecycle events (bankruptcy, liquidation, dissolution)
address - Registered address or jurisdiction changes
ownership - Beneficial ownership or shareholding changes
financial - Capital, revenue, or financial metric changes
legalRepresentatives - Legal representatives, directors, or authorized signatories
other - Any other meaningful changes (name, activities, management)
disappeared - Company no longer exists in register (triggers deactivation)

Getting Started

Step 1: Create a Monitor

To start monitoring a company, send a POST request:

curl -X POST https://api.topograph.co/v2/monitors \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "companyId": "932884117",
    "countryCode": "FR",
    "metadata": {
      "caseId": "case-12345"
    }
  }'

Response:

{
  "id": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "metadata": {
    "caseId": "case-12345"
  }
}

Important: The id returned is your Monitor ID, which you can use to stop monitoring for the related company. metadata is optional: arbitrary key-value string pairs stored on the monitor and echoed back in monitor responses and in every monitor.notification webhook. Use it to map notifications back to your internal records, such as a case or customer ID. Calling POST /v2/monitors again for the same company replaces the stored metadata when the field is provided. Limits: max 50 keys, keys up to 40 characters (longer keys are skipped), values up to 500 characters (longer values are truncated).

Step 2: Configure Webhooks

Webhooks are configured at the account level. All monitors for your account send notifications to the same webhook endpoint(s).

Step 3: Handle Webhook Events

When changes are detected, you’ll receive a webhook with this structure:

{
  "type": "monitor.notification",
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T14:23:45.678Z",
  "changeCategories": ["status", "financial"],
  "monitorHasBeenDeactivated": false,
  "metadata": {
    "caseId": "case-12345"
  }
}

Step 4: Test Your Integration

You don’t have to wait for a real change to validate your integration. From a monitor’s page in the dashboard, click Send Test Notification to deliver a real monitor.notification for that monitor to your webhook endpoint. The event is built exactly as a genuine change notification is: your own monitorId, your own metadata, the real company. This matters if your workflow routes on metadata you set at monitor creation, because the generic sample payload in the webhooks portal carries neither. You can choose the change category, and optionally send the deactivation variant (changeCategories: ["disappeared"] with monitorHasBeenDeactivated: true) to exercise your cleanup branch. Your monitor stays active and its next scheduled check is unaffected. The same call is available on the API:

curl -X POST https://api.topograph.co/v2/monitors/{monitorId}/test-notification \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "changeCategories": ["status"] }'

Both fields are optional; the default is {"changeCategories": ["other"], "monitorHasBeenDeactivated": false}. The response echoes the exact payload delivered.

A test notification is deliberately indistinguishable from a real one, so that what you test is what you’ll get in production. There is no test flag in the payload. If your pipeline opens a case for every notification, a test will open a real case.

Webhook Payload Deep Dive

Understanding Each Field

`monitorId` (string)

What it is: Unique identifier for the monitor, the same id returned by POST /v2/monitors
Format: CUID (e.g., “clh3k9n0x000008l63vog8wkp”)
Use case: Track which monitor triggered the notification, look it up with GET /v2/monitors/{id}, or stop it with DELETE /v2/monitors/{id}

`companyId` (string)

What it is: The company’s official register number
Examples: “932884117” (France), “Augsburg HRB 34617” (Germany)
Use case: Match to your internal company records

`countryCode` (string)

What it is: ISO 3166-1 alpha-2 country code
Examples: “FR”, “DE”, “GB”, “IT”
Use case: Route to country-specific handlers

`timestamp` (string)

What it is: When the change was detected (not when it occurred)
Format: ISO 8601 UTC (e.g., “2025-09-26T14:23:45.678Z”)
Use case: Order and deduplicate events

`changeCategories` (array of strings)

What it is: Types of changes detected (can be multiple)
Possible values:
- "status" - Legal status changed (active → liquidation)
- "address" - Registered address changed
- "ownership" - Shareholders or UBO changed
- "financial" - Financial metrics changed
- "legalRepresentatives" - Legal representatives or directors changed
- "other" - Other changes (name, activities, etc.)
- "disappeared" - Company no longer exists
Examples:
- ["status"] - Company entered bankruptcy
- ["address", "financial"] - Moved offices AND updated capital
- ["disappeared"] - Company dissolved and removed from register
Use case: Route to appropriate teams/systems

`metadata` (object, optional)

What it is: The key-value pairs you provided when creating the monitor
Example: { "caseId": "case-12345" }
Use case: Map the notification back to your internal records without keeping your own monitor-to-case mapping
Note: Only present when you set metadata on the monitor

`monitorHasBeenDeactivated` (boolean)

What it is: Whether this monitor is being permanently deactivated
When true: Company disappeared from register (404/not found)
When false: Normal change notification
Critical: When true, you should:
1. Remove the company from your monitoring dashboard
2. Stop expecting future notifications
3. Investigate why the company disappeared
4. The monitor cannot be reactivated - you must create a new one if the company reappears

Example Webhook Scenarios

Scenario 1: Company Enters Liquidation

{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["status"],
  "monitorHasBeenDeactivated": false
}

Example action: Raise the potential credit risk to your team.

Scenario 2: Ownership Change

{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["ownership"],
  "monitorHasBeenDeactivated": false
}

Example action: Trigger UBO re-verification.

Scenario 3: Company Disappeared

{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["disappeared"],
  "monitorHasBeenDeactivated": true
}

Example actions:

Mark company as “ceased to exist” in your system
Remove from monitoring dashboard
Alert relationship managers
Do not attempt to reactivate this monitor

Scenario 4: Multiple Changes

{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["address", "financial", "other"],
  "monitorHasBeenDeactivated": false
}

Example action: Launch a comprehensive review.

Understanding Deactivation

What Causes Automatic Deactivation?

A monitor is automatically deactivated when:

Register returns 404 - Company not found
Company marked as removed - Officially deleted from register
Persistent not found errors - Company consistently unavailable

What Happens During Deactivation?

When a company disappears, the system:

Detects the Issue
- Company fetch returns “not found” error
- System identifies this as a disappearance
Processes the Deactivation
- Logs the not-found event
- Creates final snapshot with “disappeared” status
- Sends webhook notification
- Deactivates the monitor
- Clears cached data

Sends Final Webhook

{
  "type": "monitor.notification",
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["disappeared"],
  "monitorHasBeenDeactivated": true // ← Critical flag
}

Cleanup
- Monitor is permanently deactivated
- Historical data retained for audit
- No future checks will occur

Handling Deactivation Webhooks

When you receive monitorHasBeenDeactivated: true:

// Example webhook handler
async function handleMonitoringWebhook(payload) {
  if (payload.monitorHasBeenDeactivated) {
    // Company has disappeared!
    await markCompanyAsInactive(payload.companyId);
    await removeFromMonitoringDashboard(payload.companyId);
    await notifyComplianceTeam({
      message: 'Company no longer exists in register',
      companyId: payload.companyId,
      countryCode: payload.countryCode,
    });

    // DO NOT try to recreate the monitor immediately
    // Investigate why the company disappeared first
  } else {
    // Normal change processing
    await processCompanyChanges(payload);
  }
}

Can I Reactivate a Deactivated Monitor?

No. Deactivation is permanent. If you want to monitor the company again:

Verify the company exists in the register
Create a new monitor using POST /v2/monitors
You’ll receive a new monitor ID to track the company

FAQ

What happens if a company temporarily disappears?

If a company doesn’t appear anymore in the register, the monitor is immediately deactivated. This is permanent - you’ll need to create a new monitor if the company reappears.

Can I get the actual data that changed?

Currently, webhooks only indicate what category of change occurred. Full differential data in webhooks is planned for future releases.

How is monitoring billed?

Monitoring commercial terms and eligibility can depend on your account and the countries you monitor. Check topograph.co/pricing for live coverage and use the dashboard for your account configuration.

Can I decide what changes trigger webhooks?

Not yet. All detected changes trigger webhooks. Filtering rules will be added in a future release.

What if I need to monitor thousands of companies?

The system supports large-scale monitoring. Contact support to discuss enterprise volumes.

Getting Started

Integration Guides

Core Features

Behavior & Operations

Company Monitoring

Supported Countries for Monitoring

What is Monitoring?

Core Concepts

Monitor

Change Categories

Getting Started

Step 1: Create a Monitor

Step 2: Configure Webhooks

Step 3: Handle Webhook Events

Step 4: Test Your Integration

Webhook Payload Deep Dive

Understanding Each Field

`monitorId` (string)

`companyId` (string)

`countryCode` (string)

`timestamp` (string)

`changeCategories` (array of strings)

`metadata` (object, optional)

`monitorHasBeenDeactivated` (boolean)

Example Webhook Scenarios

Scenario 1: Company Enters Liquidation

Scenario 2: Ownership Change

Scenario 3: Company Disappeared

Scenario 4: Multiple Changes

Understanding Deactivation

What Causes Automatic Deactivation?

What Happens During Deactivation?

Handling Deactivation Webhooks

Can I Reactivate a Deactivated Monitor?

FAQ

What happens if a company temporarily disappears?

Can I get the actual data that changed?

How is monitoring billed?

Can I decide what changes trigger webhooks?

What if I need to monitor thousands of companies?

​Supported Countries for Monitoring

​What is Monitoring?

​Core Concepts

​Monitor

​Change Categories

​Getting Started

​Step 1: Create a Monitor

​Step 2: Configure Webhooks

​Step 3: Handle Webhook Events

​Step 4: Test Your Integration

​Webhook Payload Deep Dive

​Understanding Each Field

​monitorId (string)

​companyId (string)

​countryCode (string)

​timestamp (string)

​changeCategories (array of strings)

​metadata (object, optional)

​monitorHasBeenDeactivated (boolean)

​Example Webhook Scenarios

​Scenario 1: Company Enters Liquidation

​Scenario 2: Ownership Change

​Scenario 3: Company Disappeared

​Scenario 4: Multiple Changes

​Understanding Deactivation

​What Causes Automatic Deactivation?

​What Happens During Deactivation?

​Handling Deactivation Webhooks

​Can I Reactivate a Deactivated Monitor?

​FAQ

​What happens if a company temporarily disappears?

​Can I get the actual data that changed?

​How is monitoring billed?

​Can I decide what changes trigger webhooks?

​What if I need to monitor thousands of companies?

Supported Countries for Monitoring

What is Monitoring?

Core Concepts

Monitor

Change Categories

Getting Started

Step 1: Create a Monitor

Step 2: Configure Webhooks

Step 3: Handle Webhook Events

Step 4: Test Your Integration

Webhook Payload Deep Dive

Understanding Each Field

`monitorId` (string)

`companyId` (string)

`countryCode` (string)

`timestamp` (string)

`changeCategories` (array of strings)

`metadata` (object, optional)

`monitorHasBeenDeactivated` (boolean)

Example Webhook Scenarios

Scenario 1: Company Enters Liquidation

Scenario 2: Ownership Change

Scenario 3: Company Disappeared

Scenario 4: Multiple Changes

Understanding Deactivation

What Causes Automatic Deactivation?

What Happens During Deactivation?

Handling Deactivation Webhooks

Can I Reactivate a Deactivated Monitor?

FAQ

What happens if a company temporarily disappears?

Can I get the actual data that changed?

How is monitoring billed?

Can I decide what changes trigger webhooks?

What if I need to monitor thousands of companies?