Create an insurance monitor

post

https://api.wingspan.app/v3/compliance/insurance-monitors

Opens a monitor tracking one payee's compliance with one existing
InsuranceMonitorConfiguration.

The body names the payerPayeeId it is acting in and no account: both
seats are resolved from the relationship, so one body serves both the
payer and the payee. A caller holding no seat on the relationship gets a
404.

The payee must cite the requirementId that justifies the create, and
the configuration comes back with that verdict — so configurationId
must be absent from the payee seat, as are externalId and a non-empty
metadata, all three of which are the payer's. The payer's direct-order
path cites no requirement and names the configuration itself.

THE ORDER OF THOSE TWO REFUSALS MATTERS. A payee must send
requirementId; without it the answer is 400 regardless of the other
fields. With it, a payee who also sends configurationId, externalId
or a non-empty metadata gets 422. So a payee body carrying a
configurationId and no requirementId answers 400, not 422 — drop
the extra field AND supply the requirement.

The coverage requirements are the configuration's and are NOT restated
here: one configuration backs many monitors, so configurationId names
an existing one created through
POST /v3/compliance/insurance-monitor-configurations.

A create that cites a requirementId is deduplicated: a repeat for the
same relationship and configuration while an earlier monitor is still
outstanding returns that monitor rather than opening a second one. Three
things opt out and open a new monitor — a payer's direct order (no
requirementId), an externalId, and a payer reset of the requirement
behind it.

Supplying an externalId already in use for this payer account returns
409 ResourceConflict; create is not an upsert.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

payerPayeeId

string

required

The PayerPayee record the monitor is opened against. Both account seats are resolved from it and neither is supplied here, so one body serves both the payer and the payee. Accepts canonical Wingspan ids and legacy composite relationship ids returned by V3 payer/payee read/list endpoints.

requirementId

string

The requirement this monitor satisfies, and what authorises the create. REQUIRED when the payee opens the monitor; absent is a 400 BadRequest. Optional for the payer, whose direct-order path needs no requirement to justify it.

configurationId

string

An existing InsuranceMonitorConfiguration owned by the relationship's payer account. The coverage requirements are the configuration's; they are not restated here, because one configuration backs many monitors.
Payer seat only, and only on the direct-order path. It must be ABSENT when the payee opens the monitor, because the authorised configuration comes back with the requirement verdict: a payee who sends it gets a 422 when a requirementId is present, and a 400 for the missing requirementId when it is not. A payer who sends it alongside requirementId has it overridden rather than refused — the authorised configuration always wins.

externalId

string

Caller-supplied reconciliation id, unique per payer account. A duplicate returns 409 ResourceConflict. Rejected from the payee seat, where the namespace is the payer's: 422 when a requirementId is present, 400 for the missing requirementId when it is not.

metadata

object

Caller annotations stored on the monitor. Rejected from the payee seat, like externalId: there is one annotation bag on the row, it is the payer's, and only the payer can update it, so a payee writing into it on create would seed a field they can never correct. 422 when a requirementId is present, 400 for the missing requirementId when it is not. An empty object is accepted from either seat and leaves the column alone.
A requirement-citing create that the duplicate check absorbs returns the monitor that already exists and does NOT merge these onto it. A payer's direct order is never absorbed, so its annotations always land.

Headers

Idempotency-Key

string

length between 1 and 255

^[\x21-\x7e]{1,255}$

Optional idempotency token for authenticated POST and PATCH requests. Reusing the same key and body returns the cached response for 24 hours, except credential operations that explicitly document a 409 because one-time secret material is never cached; reusing it with a different body returns 409 IdempotencyKeyConflict. Use 1-255 printable ASCII characters.

X-Wingspan-Account

string

^(?:[A-Za-z0-9_.]{22}|[a-f0-9]{24})$

Select the Account for an Account-scoped operation. A direct ServiceAccount API key MUST supply this header, and the target must be within the ServiceAccount owner's or Authorization grant's Account boundary. A Person bearer may select an Account on which it has an active Stakeholder, and an Account session may select its bound Account (or a descendant only when the session explicitly includes descendants).

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

201Insurance monitor created

400Malformed request syntax

401Unauthenticated

403Forbidden

404Resource not found

409Conflict

422Validation error