Alerts

Alerts are created automatically when the monitoring engine flags a transaction, when a screening hit occurs, or when an activated provider plugin pushes a webhook (e.g. Sumsub KYC rejection, ComplyAdvantage match status change). Use these endpoints to read alerts back into your own systems.

Alert triage (assigning, investigating, closing, escalating) is done by your compliance team in the WhoComply dashboard. To get notified when new alerts fire, register a webhook endpoint.

All endpoints on this page require read scope.

GET/tenants/{slug}/alerts

List alerts

Returns alerts for your tenant, newest first.

Query parameters

Name
status
Type
string
Description
Filter by status: open, investigating, escalated, or closed.
Name
customer_id
Type
uuid
Description
Restrict to alerts for a single customer.
Name
limit
Type
integer
Description
Results per page (1-100, default 20).
Name
offset
Type
integer
Description
Pagination offset (default 0).

Request

GET

/tenants/{slug}/alerts

curl "https://api.whocomply.com/api/v1/tenants/kuda-mfb/alerts?status=open&limit=10" \
  -H "Authorization: Bearer wc_..."

Response

{
  "status": "ok",
  "data": [
    {
      "id": "a1b2c3d4-...",
      "customer_id": "f1e2d3c4-...",
      "alert_type": "transaction_flag",
      "severity": "high",
      "status": "open",
      "title": "High Value Transaction over 5M",
      "created_at": "2026-04-17T08:14:33Z"
    }
  ]
}

GET/tenants/{slug}/alerts/{id}

Get alert

Returns a single alert with the full enriched context snapshot captured at the time of detection, plus provenance metadata if the alert came from a plugin.

Request

GET

/tenants/{slug}/alerts/{id}

curl "https://api.whocomply.com/api/v1/tenants/kuda-mfb/alerts/{alert_id}" \
  -H "Authorization: Bearer wc_..."

Response

{
  "status": "ok",
  "data": {
    "id": "a1b2c3d4-...",
    "customer_id": "f1e2d3c4-...",
    "alert_type": "kyc_review",
    "severity": "critical",
    "status": "open",
    "title": "Sumsub KYC rejected: SANCTIONS, PEP",
    "description": "Entity on NG PEP register and OFAC match",
    "trigger_ref": "",
    "metadata": {
      "source": "plugin",
      "plugin": "sumsub",
      "event_source": "sumsub:applicantReviewed",
      "provider_alert_id": "5d2b1a3e0000000000000001:reviewed:1777028512483",
      "reject_labels": ["SANCTIONS", "PEP"],
      "reject_type": "FINAL"
    },
    "created_at": "2026-04-17T08:14:33Z"
  }
}

GET/tenants/{slug}/alerts/{id}/activity

Alert activity

Returns the timeline of activity on an alert: comments, status transitions, assignments, escalation. Useful when displaying compliance history alongside an alert in your own system.

Request

GET

/tenants/{slug}/alerts/{id}/activity

curl "https://api.whocomply.com/api/v1/tenants/kuda-mfb/alerts/{alert_id}/activity" \
  -H "Authorization: Bearer wc_..."

Response

{
  "status": "ok",
  "data": [
    {
      "type": "status_changed",
      "from": "open",
      "to": "investigating",
      "actor": { "id": "...", "email": "officer@kuda-mfb.test", "first_name": "Funke" },
      "created_at": "2026-04-17T09:00:00Z"
    }
  ]
}

Alert object

Field	Type	Description
`id`	uuid	Unique alert identifier
`tenant_id`	uuid	Owning tenant
`customer_id`	uuid	The customer this alert relates to
`alert_type`	string	`transaction_flag`, `screening_hit`, `kyc_review`, `kyc_state`, or `plugin_alert`
`severity`	string	`low`, `medium`, `high`, or `critical`
`status`	string	`open`, `investigating`, `escalated`, or `closed`
`title`	string	Human-readable alert title
`description`	string	Detail of what triggered the alert
`trigger_ref`	string	Reference to the triggering event (e.g. transaction ID, KYT txn ID)
`assigned_to`	uuid	User the alert is assigned to (set in dashboard)
`case_id`	uuid	Case the alert was escalated into, if any
`metadata`	object	Provenance + extra context. See below
`created_at`	timestamp	When the alert was created

Alert provenance

Every alert carries a metadata object identifying its origin so your downstream systems can branch on the source if they want to.

Native engine alerts (rule fired, watchlist hit) carry minimal metadata — the rule ID, the matched watchlist source, the screening match score.

Plugin-sourced alerts (Sumsub webhook, ComplyAdvantage match) carry richer provenance:

Field	Description
`source`	`plugin` for any plugin-derived alert
`plugin`	Plugin name, e.g. `sumsub`, `complyadvantage`
`event_source`	Specific event type, e.g. `sumsub:applicantReviewed`, `complyadvantage:match_status_updated`
`provider_alert_id`	The provider's own identifier for this event
`raw_payload_sha256`	Hash of the raw webhook body for traceability
Provider-specific fields	e.g. `reject_labels`, `reject_type`, `moderation_comment` for Sumsub; `entity_id`, `entity_match_status` for ComplyAdvantage

See Integrations for the orchestration model that produces these alerts.