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

# Search monitoring (Beta)

> Receive a notification when a pending French company appears in search.

Search monitoring watches for a company before you know its registration number. Submit its name and optional address constraints, then receive a webhook when a new matching company becomes available.

> [!NOTE]
>
> Search monitoring is an opt-in beta for France. Contact [support@topograph.co](mailto:support@topograph.co) to request access. It complements [company monitoring](https://docs.topograph.co/essentials/monitoring.md), which tracks changes to a company you have already identified.

## Create a watch

```bash theme={null}
curl -X POST 'https://api.topograph.co/v2/search-monitors' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "countryCode": "FR",
    "query": "Dupont Conseil",
    "address": {"city": "Saint-Malo", "postalCode": "35400"},
    "metadata": {"caseId": "incorporation-123"}
  }'
```

The `query` contains the company name, without its address. Every name word must match. Capitalization, accents and punctuation are ignored; partial words are not matched. Each supplied city or postal code must match, and each word in an optional `addressLine1` must appear in the address. A missing address field cannot satisfy that constraint.

Use a specific name. An overly broad search is rejected rather than watching an incomplete list of results. The beta allows 100 active watches per account. Watches expire after 30 days by default; supply an ISO date-time in `expiresAt` for an earlier expiration.

The response contains the watch's `id`, status, expiration and `initialMatches`. On first creation, those matches form the starting baseline: inspect them immediately if the company may already have registered. They do not trigger new-match notifications. Reposting the same name and address returns the existing watch and its remembered matches; it does not create a second watch or extend an active watch's expiration. Supplying `metadata` replaces its metadata.

## Receive a match

New matches produce `search_monitor.match` events at your configured webhook endpoint:

```json theme={null}
{
  "type": "search_monitor.match",
  "eventId": "cmatch123",
  "monitorId": "cmonitor123",
  "countryCode": "FR",
  "candidate": {
    "id": "932884117",
    "countryCode": "FR",
    "legalName": "DUPONT CONSEIL",
    "address": {"city": "Saint-Malo", "postalCode": "35400"}
  },
  "detectedAt": "2026-10-29T14:00:00.000Z",
  "metadata": {"caseId": "incorporation-123"}
}
```

Verify the candidate's identity before associating it with your customer. The event reports a new search match, not a confirmed identity or incorporation date. It does not guarantee that every document is already available. Use the candidate's `id` to request company data and available documents separately.

Checks run hourly. Register publication and data availability determine when a company can be detected, so this is not an immediate registration alert. A previously seen company that disappears and returns does not create another match event.

A failed check preserves the previous results and sets `lastError` on the watch, for example when a name grows to match too many companies. Checks continue hourly and `lastError` disappears once one succeeds. To narrow a watch, stop it and create one with a more specific name or address.

Webhook delivery can be retried. Deduplicate using `eventId`, and follow the [webhook verification guide](https://docs.topograph.co/guides/webhooks.md). Updating watch metadata does not change events already queued for delivery.

## Manage watches

| Request | Result |
| - | - |
| `GET /v2/search-monitors` | List your watches, including expired and stopped watches; follow `nextCursor` with `?after=…`. |
| `GET /v2/search-monitors/{id}` | Read a watch's status, expiration, last successful check and `lastError`. |
| `DELETE /v2/search-monitors/{id}` | Stop new notifications. Events already accepted for delivery can still arrive. |

A match leaves the watch active so you can review multiple candidates. Stop it once you have identified the company. Reposting an expired or stopped watch restarts it for the requested duration with a fresh baseline: companies that appeared while it was off are returned in `initialMatches`, not sent as new matches.

## Test in a development environment

Development accounts can use the API without beta activation. Watches see only that account's [company fixtures](https://docs.topograph.co/guides/development-environment.md). Create the watch first, then add a matching fixture to make a new candidate appear at the next check. Events carry `environment: "development"`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.