Ongoing Monitoring

Ongoing monitoring keeps a check's subjects screened after the initial check has completed, and adds or updates findings on the check when their screening results change. For what is monitored and what counts as a match, see What is Ongoing Monitoring?

This guide covers how to start and stop monitoring through the API, how to read its state, and the notifications it produces. The part integrators most often misread: monitoring renews itself, and the expiry date on the check is the date that renewal happens — not a date monitoring stops.

The lifecycle

1. Enable monitoring when you create the check, or later with SetOngoingMonitoring.
2. Monitoring starts once the check's initial screening has run. You receive ongoing_monitoring_started with the end of the first period.
3. While it runs, any change to the subject's screening results updates the check's findings and raises ongoing_monitoring_hit.
4. About a month before each period ends you receive ongoing_monitoring_renewal_reminder. At the end of the period monitoring renews automatically, is billed for the next period, and raises ongoing_monitoring_renewed. This repeats indefinitely.
5. Disable monitoring with SetOngoingMonitoring, or cancel the check. Monitoring stops immediately and nothing further is billed.

Nothing needs to be done to keep monitoring running. The only way to stop it is to disable it.

Ongoing monitoring is available on the identity verification, client-only verification and KYB verification (preview) templates. All three enable it with the same enableOngoingMonitoring param. On a KYB check, monitoring is activated when the check completes, and only if the company screening succeeded. Until then the check does not report ongoingMonitoring.enabled as true, even when you requested monitoring at creation. If the screening did not succeed, the check completes without monitoring.

Reading the check

A check that supports ongoing monitoring carries an ongoingMonitoring object:

{
  "name": "organizations/acme-corp/teams/conveyancing/checks/01JRA4ABC123",
  "ongoingMonitoring": {
    "enabled": true,
    "activeUntil": "2027-03-14T09:12:44Z"
  }
}

• enabled is the only field that tells you whether the check is being monitored right now.
• activeUntil is the end of the current billing period. While enabled is true, this is the moment the subscription renews for another period and is billed again. Monitoring does not lapse at this date.

Two behaviours to be aware of:

• activeUntil is not cleared when monitoring is disabled. After you turn monitoring off, the check may still report a future activeUntil alongside enabled: false. That date is a leftover from the period that was already paid for; it does not mean monitoring is still running. Always read enabled.
• activeUntil is unset if monitoring has never been activated for the check — including when monitoring was requested at creation but the check has not yet reached the point of activating it.

Turning monitoring off

Disable monitoring with SetOngoingMonitoring:

curl -X POST "https://api.thirdfort.dev/client/api/v1/organizations/{org_id}/teams/{team_id}/checks/{check_id}:setOngoingMonitoring" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

This is synchronous, and by the time it returns:

• Screening has stopped at the provider — monitoring does not continue to the end of the current period.
• No further renewal will occur, and no further period will be billed.
• The period already billed is not prorated or refunded.

Re-enabling later starts monitoring again. Cancelling a check also disables its monitoring.

Enabling monitoring requires your organization's package to support it; disabling is always permitted, even if that entitlement has since lapsed, so monitoring can never get stuck on.

The renewal reminder

About a month before each renewal, a notification.client.ongoing_monitoring_renewal_reminder.v1 notification is raised carrying the check and its renewalDate. It appears in ListNotifications for your organization. It is also delivered by webhook when the check's notification recipient is your integration, or by email when the recipient is a person.

Despite the name, this is not a prompt to renew — renewal is automatic. Treat it as advance notice that the subscription is about to renew and be billed. Act on it only if you do not want that, by disabling monitoring on the check before renewalDate.

When a period does renew you receive notification.client.ongoing_monitoring_renewed.v1 with the new activeUntil.

Notifications

Each notification carries the check resource name. See Polling for Notifications for how to receive them.

Notification	When	Payload
notification.client.ongoing_monitoring_started.v1	Monitoring has started on the check	check, displayName, activeUntil (end of the first period)
notification.client.ongoing_monitoring_hit.v1	A screening update changed the check's findings	check, displayName, subjectDisplayName, clientReference, newFindingRevisionCount (findings added, updated or removed; can be zero)
notification.client.ongoing_monitoring_renewal_reminder.v1	About a month before a period renews	check, displayName, clientReference, renewalDate
notification.client.ongoing_monitoring_renewed.v1	A period has renewed and been billed	check, displayName, activeUntil (end of the new period)

Handling a hit

When you receive ongoing_monitoring_hit:

1. Fetch the check's findings with GET /v1/{check}/findings and compare them with the findings you already hold, to see what was added, updated or removed.
2. Fetch GET /v1/{check}/checkSummary for the updated recommendation and report URLs.
3. Surface the change to the user responsible for the check.

A hit can move a completed check from INACTIVE back to ACTIVE.

Reviewing findings through the API is coming soon.

Enabling monitoring

Monitoring can be switched on at check creation, via the check's params:

{
  "params": {
    "@type": "type.googleapis.com/thirdfort.client.checks.type.v1.ClientOnlyVerificationCheckParams",
    "subject": { "...": "..." },
    "enableOngoingMonitoring": true
  }
}

or at any later point with SetOngoingMonitoring and "enabled": true. Both paths lead to the same lifecycle described above.