​
Company Monitoring System

​
Supported Countries

Monitoring is available in the following countries: Europe: 🇦🇹 AT, 🇧🇪 BE, 🇨🇭 CH, 🇨🇿 CZ, 🇩🇪 DE, 🇩🇰 DK, 🇪🇸 ES, 🇫🇮 FI, 🇫🇷 FR, 🇬🇧 GB, 🇮🇪 IE, 🇲🇹 MT, 🇳🇱 NL, 🇳🇴 NO, 🇵🇱 PL, 🇵🇹 PT

​
What is Monitoring?

The Topograph Monitoring System provides automated, continuous surveillance of company data across the countries listed above. It detects meaningful changes using AI, categorizes them intelligently, and delivers real-time webhook notifications when something important happens. Think of it as a watchdog for company data that:
  • Checks daily for any changes in 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:
  1. status - Legal lifecycle events (bankruptcy, liquidation, dissolution)
  2. address - Registered address or jurisdiction changes
  3. ownership - Beneficial ownership or shareholding changes
  4. financial - Capital, revenue, or financial metric changes
  5. legalRepresentatives - Legal representatives, directors, or authorized signatories
  6. other - Any other meaningful changes (name, activities, management)
  7. disappeared - Company no longer exists in registry (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"
  }'
Response: 
{
  "id": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR"
}
Important: The id returned is your Monitor ID, which you’ll use to manage and stop monitoring this company.

​
Step 2: Configure Webhooks

Webhooks are configured at the account level via Svix. All monitors for your account will 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: 
{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T14:23:45.678Z",
  "changeCategories": ["status", "financial"],
  "monitorHasBeenDeactivated": false
}

​
Webhook Payload Deep Dive

​
Understanding Each Field

​
monitorId (string)

  • What it is: Unique identifier for the monitor
  • Format: CUID (e.g., “clh3k9n0x000008l63vog8wkp”)
  • Use case: Track which monitor triggered the notification

​
companyId (string)

  • What it is: The company’s official registry number
  • Examples: “932884117” (France), “HRB 123456” (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 registry
  • Use case: Route to appropriate teams/systems

​
monitorHasBeenDeactivated (boolean)

  • What it is: Whether this monitor is being permanently deactivated
  • When true: Company disappeared from registry (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
}
Action: Alert compliance team about potential credit risk.

​
Scenario 2: Ownership Change

{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["ownership"],
  "monitorHasBeenDeactivated": false
}
Action: Trigger UBO re-verification workflow.

​
Scenario 3: Company Disappeared

{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["disappeared"],
  "monitorHasBeenDeactivated": true
}
Action:
  1. Mark company as “ceased to exist” in your system
  2. Remove from monitoring dashboard
  3. Alert relationship managers
  4. 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
}
Action: Major restructuring detected - comprehensive review needed.

​
Understanding Deactivation

​
What Causes Automatic Deactivation?

A monitor is automatically deactivated when:
  1. Registry returns 404 - Company not found
  2. Company marked as removed - Officially deleted from registry
  3. Persistent not found errors - Company consistently unavailable

​
What Happens During Deactivation?

When a company disappears, the system:
  1. Detects the Issue
    • Company fetch returns “not found” error
    • System identifies this as a disappearance
  2. Processes the Deactivation
    • Logs the not-found event
    • Creates final snapshot with “disappeared” status
    • Sends webhook notification
    • Deactivates the monitor
    • Clears cached data
  3. Sends Final Webhook 
    {
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["disappeared"],
  "monitorHasBeenDeactivated": true // ← Critical flag
}
  4. 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 registry',
      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:
  1. Verify the company exists in the registry
  2. Create a new monitor using POST /v2/monitors
  3. 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 registry, the moitor 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 are credits consumed?

  • Successful data fetches consume credits based on the data points retrieved
  • Failed fetches (404, errors) do NOT consume credits
  • Webhook delivery is free

​
Can I filter which changes trigger webhooks?

Not yet. All detected changes trigger webhooks. Filtering rules are planned for a future release.

​
What if I need to monitor thousands of companies?

The system handles large-scale monitoring efficiently with parallel processing. Contact sales@topograph.co for enterprise volume discussions.