Policies & Coverage

A Policy is the master insurance contract between an insurer and an Account (an employer group or an individual). This page walks through the full lifecycle from quote to cancellation.

---

Policy Lifecycle

A policy begins as a Quote — a priced proposal. Once accepted and underwritten, the quote converts to an active Policy. The policy accumulates PolicyTerm records as it renews annually. At any point it can be endorsed (mid-term changed), lapsed for non-payment, or explicitly cancelled.

---

PolicyStatus State Machine

Status	Description
ACTIVE	Coverage is in force. Claims are adjudicable.
LAPSED	Premium unpaid beyond the grace period. Coverage suspended; new claims rejected. Reinstatement possible.
CANCELLED	Irrevocably terminated. No further claims accepted.
EXPIRED	Policy term ended and renewal was not completed.

---

PolicyTerm and PolicyElement

PolicyTerm

Each annual (or custom-length) coverage period is a PolicyTerm. Key fields:

Field	Type	Notes
TermNumber	int	Sequential counter (1, 2, 3 …)
EffectiveFrom	date	Inclusive start of coverage
EffectiveTo	date	Inclusive end of coverage
Status	string	Mirrors the parent Policy.Status

PolicyElement

A PolicyElement represents one insured unit within a term — either an employee or a dependent. It carries the per-member benefit schedule as a CoverageTerms JSON blob.

Field	Type	Notes
ElementType	string	"employee" or "dependent"
Status	string	ACTIVE or REMOVED
PartyID	uuid	Links to the Party (person)
StaticID	uuid	Stable across term versions; used for accumulator tracking
EffectiveFrom	date	When this element became active
EffectiveTo	date*	Null if currently active
CoverageTerms	jsonb	Copay, coinsurance, deductible, OOP max per benefit category

---

Quote → Policy Issuance Flow

Key structs in this flow:

• Quote — holds Status QuoteStatus, ProductVersionID, and a Document JSONB blob with the rated premium, benefit schedule, and applicant data.
• QuoteEvent — immutable audit trail of every status change on the quote.
• UnderwritingFlag — records an individual underwriter decision (APPROVE, BLOCK, or DECLINE) applied to a quote. Multiple flags can coexist; the strictest wins.
• Policy — created when the quote reaches ACCEPTED and the first premium is collected. Policy.QuoteID links back to the originating quote.

---

Enrollment, Renewal, Endorsement, and Cancellation

All post-issuance changes are tracked as PolicyTransaction records:

Category	When used	Typical status progression
ISSUANCE	Policy first bound	DRAFT → PRICED → UNDERWRITTEN → APPLIED
RENEWAL	Annual term rollover	DRAFT → PRICED → APPLIED
ENDORSEMENT	Mid-term change (add dependent, change address)	DRAFT → PRICED → APPLIED
CANCELLATION	Policy terminated	DRAFT → APPLIED
REINSTATEMENT	Lapsed policy restored	DRAFT → APPLIED
REVERSAL	Corrects a previous transaction	DRAFT → REVERSED

Each transaction optionally references a TermID to anchor it to a specific coverage period. The EffectiveDate field controls when the change takes economic effect (which may differ from the processing date).

---

Key Go Struct Fields at a Glance

type Policy struct {
    ID               uuid.UUID
    Locator          string       // human-readable ref (e.g. "POL-2026-001234")
    AccountID        uuid.UUID    // billing account owner
    QuoteID          *uuid.UUID   // nil if not quote-originated
    ProductVersionID uuid.UUID    // the product/plan version
    Status           PolicyStatus // ACTIVE | LAPSED | CANCELLED | EXPIRED
    InceptionDate    time.Time    // date coverage first started
    Jurisdiction     string       // regulatory jurisdiction (e.g. "GB-ENG")
    BrokerLocator    *string      // optional broker reference
    Document         []byte       // jsonb: full policy document snapshot
}