Watches

A watch subscribes you to changes on a specific French company identified by its SIREN number. You can create watches scoped to specific event categories or receive all events.

POST /v1/monitoring/watches

Create a new watch.

Authentication: Secret API key

Request body

{
  "siren": "443061841",
  "categories": ["governance_change", "capital_change"],
  "notificationChannels": ["webhook", "email"]
}

Field	Type	Required	Description
`siren`	string	Yes	9-digit SIREN number of the company to watch
`categories`	string[]	No	Event categories to monitor. Omit to watch all categories.
`notificationChannels`	string[]	No	How to be notified: `"webhook"`, `"email"`, or both. Defaults to `["webhook"]`.

Response `201`

{
  "id": "3f2b8c1d-5e4a-4f6b-8c9d-0e1f2a3b4c5d",
  "userId": "b1c2d3e4-...",
  "organizationId": "a0b1c2d3-...",
  "siren": "443061841",
  "categories": ["governance_change", "capital_change"],
  "notificationChannels": ["webhook", "email"],
  "active": true,
  "createdAt": "2025-06-01T10:00:00.000+00:00",
  "updatedAt": "2025-06-01T10:00:00.000+00:00"
}

Response `409`

Creating a second watch for a SIREN you already watch returns a conflict:

{ "error": "Watch already exists for this SIREN" }

curl example

curl -X POST https://api.verifiables.com/v1/monitoring/watches \
  -H "Authorization: Bearer oat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "siren": "443061841",
    "categories": ["governance_change", "collective_proceeding"]
  }'

GET /v1/monitoring/watches

List all watches for your account. Results are paginated.

Authentication: Secret API key

Query parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number
`perPage`	number	`25`	Results per page (max 100)

Response `200`

{
  "meta": {
    "total": 1,
    "perPage": 25,
    "currentPage": 1,
    "lastPage": 1
  },
  "data": [
    {
      "id": "3f2b8c1d-5e4a-4f6b-8c9d-0e1f2a3b4c5d",
      "siren": "443061841",
      "categories": ["governance_change", "capital_change"],
      "notificationChannels": ["webhook", "email"],
      "active": true,
      "createdAt": "2025-06-01T10:00:00.000+00:00",
      "updatedAt": "2025-06-01T10:00:00.000+00:00"
    }
  ]
}

curl example

curl https://api.verifiables.com/v1/monitoring/watches \
  -H "Authorization: Bearer oat_your_secret_key"

DELETE /v1/monitoring/watches/:id

Remove a watch. Events already collected are retained.

Authentication: Secret API key

Path parameters

Parameter	Type	Description
`id`	string	Watch ID

Response `204`

No content.

curl example

curl -X DELETE https://api.verifiables.com/v1/monitoring/watches/3f2b8c1d-5e4a-4f6b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer oat_your_secret_key"

Alerts

Each watch has a per-category alert configuration. Every category is assigned a mode:

Mode	Behavior
`immediate`	Notify as soon as the event is detected
`digest`	Batch into a daily or weekly digest
`muted`	No notification (the event is still stored and queryable)

By default, critical categories (radiation, dissolution, collective_proceeding) are immediate, unknown is muted, and everything else goes to the digest.

GET /v1/monitoring/watches/:watchId/alerts

Get the current alert configuration for a watch. If you have never customized it, the defaults are returned.

Authentication: Secret API key

Response `200`

{
  "watchId": "3f2b8c1d-5e4a-4f6b-8c9d-0e1f2a3b4c5d",
  "categoryModes": {
    "radiation": "immediate",
    "dissolution": "immediate",
    "collective_proceeding": "immediate",
    "governance_change": "digest",
    "capital_change": "digest",
    "unknown": "muted"
  },
  "digestFrequency": "daily",
  "mutedUntil": null,
  "escalationEmail": null,
  "escalationThresholdCount": null,
  "escalationThresholdHours": null
}

Field	Type	Description
`categoryModes`	object	Map of event category to `immediate`, `digest`, or `muted`
`digestFrequency`	string	`daily` or `weekly`
`mutedUntil`	string \| null	ISO date; all notifications paused until then
`escalationEmail`	string \| null	Email notified when the escalation threshold is reached
`escalationThresholdCount`	number \| null	Number of events that triggers an escalation
`escalationThresholdHours`	number \| null	Window (hours) for counting events toward escalation

PUT /v1/monitoring/watches/:watchId/alerts

Update the alert configuration for a watch. All fields are optional; omitted fields fall back to their defaults.

Authentication: Secret API key

Request body

{
  "categoryModes": {
    "governance_change": "immediate",
    "accounts_filed": "muted"
  },
  "digestFrequency": "weekly",
  "escalationEmail": "alerts@example.com",
  "escalationThresholdCount": 3,
  "escalationThresholdHours": 24
}

curl example

curl -X PUT https://api.verifiables.com/v1/monitoring/watches/3f2b8c1d-5e4a-4f6b-8c9d-0e1f2a3b4c5d/alerts \
  -H "Authorization: Bearer oat_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "categoryModes": { "governance_change": "immediate" },
    "digestFrequency": "weekly"
  }'

On this page