Monitoring Alerts over the API

This guide is for engineers consuming monitoring alerts programmatically through the Connect API — for example to feed your own case-management system or risk engine. For what generates alerts and when, see The Monitoring System; for the in-app workflow, see Working with Monitoring Alerts.

The model

Three operations cover the full loop:

An alert is a lightweight envelope: something changed on this entity in this dataset. The envelope carries identity, timing, and state; the actual change content (before/after values) lives behind alertData.

Listing alerts

query {
  alerts(where: { states: [UNRESOLVED], kinds: [PEP, SANCTIONS], page: { limit: 50, offset: 0 } }) {
    edges {
      node {
        id
        kind # PEP | SANCTIONS | RELATIONS | COMPANY_INFORMATION
        state # UNRESOLVED | RESOLVED
        insertedAt
        computedAt
        resolvedBy
        resolvedAt
      }
    }
  }
}

Filters available in where:

• states — UNRESOLVED and/or RESOLVED
• kinds — the four dataset kinds: PEP, SANCTIONS, RELATIONS, COMPANY_INFORMATION
• entity — all alerts for one entity id
• entityKind — defaults to COMPANY; set explicitly if you monitor private persons
• period — a time window on alert creation
• page — limit/offset pagination

Fetching what changed

query {
  alertData(alert: "<alert-id>") {
    # The change that triggered the alert, including before/after values.
    # The shape depends on the alert's dataset kind (a screening-hit change,
    # a relation change, or a company-information field change), and includes
    # settings context when the alert stems from a team-settings change.
  }
}

Use alertData lazily — fetch it when your system actually processes the alert, not while listing.

Resolving alerts

mutation {
  alertUpdate(where: { ids: ["<alert-id-1>", "<alert-id-2>"], state: RESOLVED }) {
    ids
  }
}

• The only states are UNRESOLVED and RESOLVED — resolving is reversible.
• Resolution over the API is recorded in the same audit trail as in-app resolution (resolvedBy, resolvedAt), and alerts you resolve over the API disappear from your team’s in-app queue too. One resolution model, two interfaces.
• There is no assignee or comment field on the Connect alert surface — assignment is entity-level and managed in the app.

Integration pattern

The recommended loop for syncing alerts into your own system:

1. Poll alerts(where: { states: [UNRESOLVED] }) on a schedule that matches the screening cadence — companies are screened five nights per week, private persons daily, so polling more often than hourly buys nothing. See screening cadence.
2. Deduplicate on alert id; use insertedAt for incremental fetching.
3. Fetch details via alertData for the alerts your process actually handles.
4. Resolve via alertUpdate once handled on your side, so both systems agree on what’s outstanding.

If you prefer push over poll, see Webhooks for event delivery, and combine: webhook as the trigger, alerts as the source of truth.

Related pages

• Syncing Your Customer List — getting entities into monitoring over the API
• Monitoring Alerts Settings — which alert categories your team has enabled (the API only returns alerts for enabled categories)
• API FAQ