Identity verification monitors and alerts

An identity verification monitor re-screens a subject on a schedule. When a screening finds a possible match, the monitor raises an alert. You review each alert and either clear it or confirm it.

This page describes how the API behaves. It isn't legal advice, and an alert disposition isn't a legal determination.

Prerequisites

A Person credential. All eleven calls on this page are Person-scoped; sending X-Wingspan-Account returns 400 AccountScopeNotApplicable.
The subject's id. For Payee, Payer, and Stakeholder subjects, use the relationship record id, not a linked Account or Person id.

Endpoints

Method and path	Operation
`POST /v3/onboarding/identity-verification-monitors`	`createIdentityVerificationMonitor`
`GET /v3/onboarding/identity-verification-monitors`	`listIdentityVerificationMonitors`
`GET /v3/onboarding/identity-verification-monitors/{monitorId}`	`getIdentityVerificationMonitor`
`POST .../{monitorId}/pause`	`pauseIdentityVerificationMonitor`
`POST .../{monitorId}/resume`	`resumeIdentityVerificationMonitor`
`POST .../{monitorId}/cancel`	`cancelIdentityVerificationMonitor`
`GET .../{monitorId}/alerts`	`listIdentityVerificationMonitorAlerts`
`GET /v3/onboarding/identity-verification-alerts`	`listIdentityVerificationAlerts`
`GET /v3/onboarding/identity-verification-alerts/{alertId}`	`getIdentityVerificationAlert`
`POST .../{alertId}/confirm`	`confirmIdentityVerificationAlert`
`POST .../{alertId}/clear`	`clearIdentityVerificationAlert`

.../{monitorId} and .../{alertId} abbreviate the full paths above.

1. Create a monitor

Field	Required	Notes
`subject`	Yes	`{ "type": "Account" \| "Person" \| "Payee" \| "Payer" \| "Stakeholder", "id": "..." }`.
`tier`	Yes	`Tax`, `BankingGrade`, or `Enhanced`.
`cadence`	No	`Daily`, `Weekly`, or `Monthly`. Default `Monthly`.
`monitoredCheckTypes`	No	Screening checks only: `OfacScreening`, `PepScreening`, `AdverseMedia`.
`identityVerificationId`	No	The verification that led to this monitor. Omit to create a standalone monitor.
`externalId`	No	Your own id, up to 200 characters.
`metadata`	No	Key-value strings.

curl -X POST https://api.wingspan.app/v3/onboarding/identity-verification-monitors \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": { "type": "Payee", "id": "Pq3rTn8LwX5sYb2kMc7dVa" },
    "tier": "BankingGrade",
    "cadence": "Weekly",
    "monitoredCheckTypes": ["OfacScreening", "PepScreening"]
  }'

The 201 response is the monitor with status: "Active", events.nextRunAt, and an ETag header.

Status	When
`409 VerificationMonitorAlreadyExists`	An active monitor already exists for the same `subject.type`, `subject.id`, and `tier`.
`409 ResourceConflict`	`externalId` is already used by another monitor of yours. Create isn't an upsert; find the existing one with `filter[externalId][eq]`.
`422 UnsupportedValue`	An entry in `monitoredCheckTypes` isn't a screening check.

2. Pause, resume, or cancel

Call	Allowed from	Result
`pause`	`Active`	`Paused`. No new alerts are produced.
`resume`	`Paused`	`Active`. Alerts resume on the next cadence tick.
`cancel`	The spec doesn't list the allowed states	`Cancelled`. Terminal. You can create a new monitor for the same subject and tier afterwards.

Each takes no body, accepts Idempotency-Key and If-Match, and returns the updated monitor. A call from a state that doesn't allow it returns 409, and a stale If-Match returns 412. Monitor statuses are Active, Paused, and Cancelled.

3. List monitors

GET /v3/onboarding/identity-verification-monitors sorts by -createdAt by default and supports sort and page[size]/page[token]. Filters, each with [eq]: externalId, status, subjectType, subjectId, tier. Example: ?filter[status][eq]=Active&filter[subjectType][eq]=Payee.

4. Review alerts

List alerts for one monitor with GET .../{monitorId}/alerts, or across all monitors with GET /v3/onboarding/identity-verification-alerts. Alert filters, each with [eq]: status, severity, externalId, and on the cross-monitor list also monitorId and category.

An alert has monitorId, severity (Low, Medium, High, Critical), category (for example OfacSanctions, Pep, AdverseMedia), checkType, status, and a match object with name, score (0 to 100, higher is more concerning), source, and details. Critical means an exact OFAC or PEP match.

Alert status starts as Open. A reviewer moves it to one of two terminal states, and they exclude each other:

Call	New status	Use when
`POST .../{alertId}/clear`	`Cleared`	The match is a false positive or is otherwise resolved.
`POST .../{alertId}/confirm`	`Confirmed`	The match is valid and needs action.

Both take no body and accept Idempotency-Key and If-Match. They set events.clearedAt or events.confirmedAt and actors.clearedBy or actors.confirmedBy. An alert that's no longer Open returns 409; a stale If-Match returns 412; an unknown id returns 404.

Webhooks

The catalog lists IdentityVerificationMonitor.* and IdentityVerificationMonitorAlert.* events. Subscribe with POST /v3/platform/webhooks. See Webhooks and events.