> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topograph.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Company Monitoring

> Documentation on the feature to track company changes

## Supported Countries for Monitoring

Monitoring is available in many countries. See the full list and live coverage at [topograph.co/pricing](https://topograph.co/pricing).

<Info>
  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.
</Info>

## 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:

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
  }
}
```

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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**

   ```json theme={null}
   {
     "type": "monitor.notification",
     "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`:

```javascript theme={null}
// 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 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](https://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.