Requirement monitors

A monitor is the lifecycle view of one requirement. It shows what backs the requirement right now, when the current result stops being valid, and what happened before. Use these calls to renew a requirement that's expiring, or to pause and cancel one.

These are not the identity-verification monitors. For those, see Identity verification monitors and alerts.

Prerequisites

An Account credential, with X-Wingspan-Account if you act on a child Account. Monitor calls are Account-scoped.
Scopes: compliance.monitor:read for reads, compliance.monitor:write for the rest.
A requirement id, for example from GET /v3/onboarding/requirements.

Endpoints

Method and path	Operation
`POST /v3/onboarding/monitors`	`createMonitor`
`GET /v3/onboarding/monitors`	`listMonitors`
`GET /v3/onboarding/monitors/{monitorId}`	`getMonitor`
`POST /v3/onboarding/monitors/{monitorId}/renew`	`renewMonitor`
`POST /v3/onboarding/monitors/{monitorId}/pause`	`pauseMonitor`
`POST /v3/onboarding/monitors/{monitorId}/resume`	`resumeMonitor`
`POST /v3/onboarding/monitors/{monitorId}/cancel`	`cancelMonitor`

How a monitor maps to a requirement

A monitor is 1:1 with a requirement, and monitorId equals requirementId. Both the payer and the payee Account of the requirement can read it.

POST /v3/onboarding/monitors takes one field, requirementId, and returns 201 with the monitor for that requirement. It doesn't create a second record. It returns 404 when the requirement isn't one your Account is payer or payee on.

Read a monitor

curl https://api.wingspan.app/v3/onboarding/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $WINGSPAN_TOKEN"

// 200 OK (trimmed)
{
  "id": "Rq5vTn2LwX8sYb4kMc9dZe",
  "requirementId": "Rq5vTn2LwX8sYb4kMc9dZe",
  "type": "InsuranceCoverage",
  "state": "Watching",
  "currentAction": { "type": "InsuranceMonitor", "id": "Im8kQ3pLx2RtVb6mHc1dZa" },
  "validUntil": "2027-03-01T00:00:00.000Z",
  "lastObservedAt": "2026-09-14T16:02:11.000Z",
  "history": [],
  "events": { "createdAt": "2026-09-01T12:00:00.000Z", "pausedAt": null, "cancelledAt": null }
}

Key fields:

Field	Meaning
`type`	The requirement type, such as `Signature`, `DocumentUpload`, `BackgroundCheck`, `BiometricIdentityVerification`, `InsuranceCoverage`, `Registration`, `PayoutMethod`, `TaxVerification`, `EmployeeTaxForms`, or `Custom`.
`state`	See the table below.
`currentAction`	The backing resource now being observed: `{ type, id }`. `null` when the requirement has none.
`validUntil`	When the current result expires. Copies the requirement's `expiresAt`.
`history[]`	Earlier backing resources that were reset, newest last, each with `supersededAt` and `reason`.
`lastObservedAt`	When the requirement last completed.
`events`, `actors`	Created, renewed, lapsed, paused, resumed, and cancelled times, and who paused, resumed, or cancelled.

States

`state`	Returned when
`Cancelled`	The requirement was cancelled. Terminal.
`Paused`	The latest pause is newer than the latest resume.
`Lapsed`	The requirement is `Inactive` or its `validUntil` has passed.
`Watching`	The requirement is `Complete` or `PendingReview`.
`Idle`	Anything else, such as `Incomplete`.

Two more states cover renewal. ExpiringSoon means the validity ends within renewLeadDays. Renewing means a fresh action is in flight. A monitor returns to Watching when a renewal completes, or goes to Lapsed when validity passes with no completed renewal.

List monitors

GET /v3/onboarding/monitors returns the monitors where your Account is payer or payee, newest first, with page[size] and page[token]. There are no filter parameters.

Renew, pause, resume, cancel

All four take no body, accept an Idempotency-Key, and return the updated monitor with 200.

Call	Use for
`renew`	An expired or expiring monitor.
`pause`	An active monitor.
`resume`	A paused monitor.
`cancel`	Ending the monitor. Terminal.

Errors: 404 when the monitor isn't visible to your Account, and 409 when the monitor's current state doesn't allow the transition. A requirement whose monitor is paused or cancelled also returns 409 from the requirement's own backing-resource calls. See Requirements and eligibility.

Webhooks

The catalog lists Monitor.* events: Created, ExpiringSoon, Renewing, Renewed, Lapsed, Paused, Resumed, and Cancelled. Subscribe with POST /v3/platform/webhooks. See Webhooks and events.

Requirements and eligibility