Skip to main content

​
Supported Countries for Monitoring

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

​
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:
  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 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"
  }'
Response: 
{
  "id": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR"
}
Important: The id returned is your Monitor ID, which you can use to stop monitoring for the related 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 register 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 register
  • Use case: Route to appropriate teams/systems

​
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 workflow.

​
Scenario 3: Company Disappeared

{
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T10:15:00.000Z",
  "changeCategories": ["disappeared"],
  "monitorHasBeenDeactivated": true
}
Example actions:
  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
}
Example action: Launch a comprehensive review.

​
Understanding Deactivation

​
What Causes Automatic Deactivation?

A monitor is automatically deactivated when:
  1. Register returns 404 - Company not found
  2. Company marked as removed - Officially deleted from register
  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 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:
  1. Verify the company exists in the register
  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 register, 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 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 handles large-scale monitoring efficiently with parallel processing. Contact [email protected] to discuss enterprise volumes.