REFERENCE · CONSUMERS AND REQUIREMENT SETS
POST /v1/engagements
Explicit engagement. Implicit on first document otherwise. Idempotent on insured_ref + consumer_ref + requirement_set (0015): seeding test data with outreach: hold and releasing it later is the same call twice, with the same requirement_set both times.
PARAMETERS
| NAME | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
| Idempotency-Key | string | no | Optional, and the preferred way to make a retry safe. Send one on every POST and PUT; a replay returns the original response with idempotent_replay true and creates nothing new. POST /documents also accepts an idempotency_key form field as an alias; the header wins when both are sent |
| insured_ref | string | yes | |
| consumer_ref | string | yes | |
| requirement_set | string | no | Optional; the consumer's requirement set (lineage key) this engagement follows (0015). Omitted uses the consumer's single set, or the one named default; 422 if the consumer carries several and none is default. 404 if the key is unknown |
| starts_on | string | no | |
| ends_on | string | no | |
| requirement_set_version | integer | no | Pins a version within that requirement set; default latest published |
| reverification_cadence | enum | no | Overrides the requirement set version's set-level reverification_cadence for this engagement |
| expiry_lead_days | integer | no | Overrides the requirement set version's set-level expiry_lead_days for this engagement |
| clock | object | no | Per-engagement clock, in business-day hours. Each field is optional and a missing one keeps the default (target 48, hard 72, escalate 36). 1 <= target_hours <= hard_hours <= 2160 and escalate_at_hours <= hard_hours, else 422. Once a clock has opened on an engagement with outreach auto, a different clock is ignored and the response carries notes: ["clock_locked"]. POST /documents takes the same object as a JSON form field |
| outreach | enum | no | auto (default) lets Insurance Verified contact the source for every line whose clock opens. hold opens the clocks and threads but never drafts or sends, and held clocks do not run out (a timeout means the source was asked); POST again with auto to release them, which restarts the clocks from that moment. Use hold while seeding history or before you are ready for the source to hear from you One of: auto, hold. |
RESPONSE
| FIELD | TYPE | DESCRIPTION |
|---|---|---|
| id | string | |
| engagement_id | string | Same value as id |
| insured_ref | string | |
| insured_name | string | |
| consumer_ref | string | |
| consumer_name | string | |
| status | enum | active, ended. |
| requirement_set | object | The requirement set (lineage) an engagement follows (0015); null before the consumer has published one |
| starts_on | string | |
| ends_on | string | |
| requirement_set_version | string | Deprecated; use requirement_set.version |
| reverification_cadence | enum | Overrides the requirement set version's set-level reverification_cadence for this engagement |
| expiry_lead_days | integer | Overrides the requirement set version's set-level expiry_lead_days for this engagement |
| outreach | enum | auto, hold. |
| grace_until | timestamp | |
| created_at | timestamp | |
| surface_check | object | The current surface check, or null before extraction has produced one |
| verdict | object | The current engagement roll-up verdict, or null before it is issued |
| line_verdicts | object[] | The current verdict for each coverage line that has resolved |
| enrollments | object[] | The insured's program enrollments on this account (4.5.1) |
| coverage_lines | object[] | |
| documents | object[] | |
| outstanding | object[] | Asks open with the insured. complete_declarations_packet: a page was marked not usable (no policy number, or another fact that could not be read); your system asks the insured for the paper, and the item is listed until a document with the policy number arrives. escalated_to_iv: a page for the coverage type is with Insurance Verified's reviewers; nothing is asked of the insured. insured_contact_missing: no phone or email is on file for the insured and the outreach has a step to them; add one with PUT /insureds/{insured_ref}, and the item clears |
| events | object[] | Newest first |
Errors: 400, 401, 403, 404, 409, 422, 429, 500. Every error body carries error.code, error.message, and error.request_id.