REFERENCE · ENGAGEMENTS

POST /v1/engagements/{engagement_id}/end

End a verification. Ends the engagement: status becomes ended, no new clock opens for it, and its open clocks close with close_reason engagement_ended (a clock another active engagement still uses stays open for that one). A request closed this way is billed as closed without a verdict; documents read for the engagement whose lines never opened a clock are billed as surface checks. Ending an ended engagement changes nothing. Returns the engagement.

PARAMETERS

NAME	TYPE	REQUIRED	DESCRIPTION
engagement_id	string	yes

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: 401, 403, 404, 429, 500. Every error body carries error.code, error.message, and error.request_id.

import requests url = "https://api.insuranceverified.ai/v1/engagements/…/end" headers = { "Authorization": "Bearer ive_live_…", "Idempotency-Key": "…", } response = requests.post(url, headers=headers) print(response.status_code, response.json())

const url = "https://api.insuranceverified.ai/v1/engagements/…/end"; const response = await fetch(url, { method: "POST", headers: { "Authorization": "Bearer ive_live_…", "Idempotency-Key": "…" }, }); console.log(response.status, await response.json());

{ "id": "…", "engagement_id": "…", "insured_ref": "…", "insured_name": "…", "consumer_ref": "…", "consumer_name": "…", "status": "active", "requirement_set": { "key": "…", "permanent_id": "…", "version": 0, "id": "…" }, "starts_on": "…", "ends_on": "…", "requirement_set_version": "…", "reverification_cadence": "monthly", "expiry_lead_days": 0, "outreach": "auto", "grace_until": "…", "created_at": "…", "surface_check": { "verdict_id": "…", "kind": "surface", "scope": "engagement", "coverage_line_id": null, "insured_ref": "…", "consumer_ref": "…", "engagement_id": "…", "requirement_set": { "key": "default", "version": 3 }, "requirement_set_version": 3, "issued_at": "…", "issued_by": "engine", "status": "compliant", "grace_until": null, "rules": [ { "rule_key": "general_liability.limit_min.each_occurrence", "surface": "pass", "result": "unverified", "severity": "hard", "reasons": [ "verification_pending" ], "flags": [], "required": { "amount": 1000000 }, "observed": { "amount": 1000000 }, "document_class_required": "coi", "document_class_observed": "coi", "verification_required": "broker", "verification_observed": null, "coverage_line_id": "…", "satisfied_by": null, "satisfied_via_parent": null, "satisfied_via_program": null, "alternatives": null, "fact_ids": [ "…" ], "document_ids": [ "…" ] } ], "wording": { "summary": "…", "next": "…", "contractual": false }, "supersedes": "prior_verdict_id", "test": false }, "verdict": { "verdict_id": "…", "kind": "surface", "scope": "engagement", "coverage_line_id": null, "insured_ref": "…", "consumer_ref": "…", "engagement_id": "…", "requirement_set": { "key": "default", "version": 3 }, "requirement_set_version": 3, "issued_at": "…", "issued_by": "engine", "status": "compliant", "grace_until": null, "rules": [ { "rule_key": "general_liability.limit_min.each_occurrence", "surface": "pass", "result": "unverified", "severity": "hard", "reasons": [ "verification_pending" ], "flags": [], "required": { "amount": 1000000 }, "observed": { "amount": 1000000 }, "document_class_required": "coi", "document_class_observed": "coi", "verification_required": "broker", "verification_observed": null, "coverage_line_id": "…", "satisfied_by": null, "satisfied_via_parent": null, "satisfied_via_program": null, "alternatives": null, "fact_ids": [ "…" ], "document_ids": [ "…" ] } ], "wording": { "summary": "…", "next": "…", "contractual": false }, "supersedes": "prior_verdict_id", "test": false }, "line_verdicts": [ { "verdict_id": "…", "kind": "surface", "scope": "engagement", "coverage_line_id": null, "insured_ref": "…", "consumer_ref": "…", "engagement_id": "…", "requirement_set": { "key": "default", "version": 3 }, "requirement_set_version": 3, "issued_at": "…", "issued_by": "engine", "status": "compliant", "grace_until": null, "rules": [ { "rule_key": "general_liability.limit_min.each_occurrence", "surface": "pass", "result": "unverified", "severity": "hard", "reasons": [ "verification_pending" ], "flags": [], "required": { "amount": 1000000 }, "observed": { "amount": 1000000 }, "document_class_required": "coi", "document_class_observed": "coi", "verification_required": "broker", "verification_observed": null, "coverage_line_id": "…", "satisfied_by": null, "satisfied_via_parent": null, "satisfied_via_program": null, "alternatives": null, "fact_ids": [ "…" ], "document_ids": [ "…" ] } ], "wording": { "summary": "…", "next": "…", "contractual": false }, "supersedes": "prior_verdict_id", "test": false } ], "enrollments": [ { "enrollment_id": "…", "program_ref": "…", "program_name": "…", "coverage_type": "…", "verification": "attestation", "insured_ref": "…", "enrolled": false, "active": false, "effective_on": "…", "ends_on": "…", "source": "…", "external_id": "…", "actor": "…", "meta": {}, "created_at": "…", "updated_at": "…", "test": false } ], "coverage_lines": [ { "coverage_line_id": "…", "coverage_type": "…", "policy_number": "…", "carrier_name": "…", "corrections": [ { "field": "policy_number", "value": "…", "entered_by": "…", "document_id": "…", "page": 0, "at": "…" } ], "document_class": "coi", "verification_state": "claimed", "effective_date": "…", "expiration_date": "…", "request": { "request_id": "…", "insured_ref": "…", "consumer_ref": "…", "coverage_line_id": "…", "opened_at": "…", "sla_target_at": "…", "sla_hard_at": "…", "status": "open", "closed_at": "…", "close_reason": "…", "verification_attempts": [ { "method": "…", "counterparty": "…", "counterparty_source": "…", "state": "…", "messages_sent": "…", "opened_at": "…", "last_outbound_at": "…", "next_action_at": "…", "closed_at": "…", "close_reason": "…" } ], "extensions": [ { "extended_by": "…", "extended_at": "…", "hours": "…", "reason": "…" } ], "total_extension_hours": 0, "final_verdict_id": "…", "engagement_ids": [ "…" ], "test": false }, "verdict_id": "…" } ], "documents": [ { "document_id": "…", "filename": "…", "doc_type": "…", "pages": 0, "status": "received", "outcome": "…", "received_at": "…", "kind": "file", "page_documents": [ { "document_id": "…", "position": 0, "filename": "…", "doc_type": "…" } ] } ], "outstanding": [ { "kind": "complete_declarations_packet", "remediation_id": "…", "coverage_type": "…", "document_id": "…", "requested_at": "…", "sentence": "…" } ], "events": [ { "type": "…", "at": "…", "subject_type": "…", "subject_id": "…" } ] }