Skip to main content
This page traces a realistic policy through its full lifecycle — creation, multiple endorsements, backdated corrections, cancellation, reinstatement, and transaction deletion. Each step shows the request payload and resulting segments. If you haven’t read the Concepts page yet, start there for an introduction to transactions, deltas, and segments.

​
Scenario

InsuredGreenfield Medical Center
LineProfessional Liability — Medical Facility
TermJanuary 1, 2025 – December 31, 2025

​
Delta Actions Reference

ActionDescriptionMatching
ModifyReplace a scalar or entire objectN/A — overwrites
AddAppend to a collection (set semantics)Objects by id, primitives by equality
RemoveRemove from a collectionObjects by id, primitives by equality

​
Premiums and Billing

Policy financial data lives at two levels: per-segment rating and full-term billing.

​
Per-Segment Rating

Each segment carries its own rating data — a PolicyRatingResponse on the policy and an ExposureRatingResponse on each exposure. These typically include:
  • annualPremium — the premium as if that segment’s state applied for the full policy year
  • proratedPremium — the actual premium contribution for that time slice
These per-segment values provide visibility into why the premium is what it is — which exposures contribute how much over which periods.

​
Full-Term Billing

fullTermPolicyBilling is a cross-segment invariant — it’s identical across every segment in a version. It contains the billing summary for the entire policy term: 
"fullTermPolicyBilling": {
  "policyPremium": 85000,
  "policyTaxes": 4250,
  "policyFees": 500,
  "policyGrandTotal": 89750
}
Every endorsement should include a fullTermPolicyBilling delta with startDate/endDate spanning the full policy term (not just the endorsement effective date). This keeps the billing summary current.
fullTermPolicyBilling is not necessarily the sum of prorated slices. Full-term billing can include flat premium minimums, surplus lines taxes, policy fees, or other adjustments that are independent of per-segment proration. The FullTermPolicyRatingResponse (a separate cross-segment field) captures these aggregate rating details.

​
Minimal vs Full Tracking

Callers are not required to pass per-segment field changes. You could submit endorsements that only modify fullTermPolicyBilling and leave per-segment data untouched. However, this reduces the system to importing transaction bordereau — you’d know the billing changed, but not what policy details produced the change.Per-segment deltas capture the actual changing characteristics of the policy over time: which exposures were added, which physicians changed, when beds were decommissioned. This is the difference between a ledger of billing events and a true temporal record of the policy.

​
In This Walkthrough

Each transaction below includes structural per-segment deltas, per-segment PolicyRatingResponse and ExposureRatingResponse rating, and the fullTermPolicyBilling update. The segment tables include a Policy Annualized Premium column — notice that this per-segment rate typically does not match the fullTermPolicyBilling.policyPremium shown below each table.

​
Creation

Effective: Jan 1 · Version: 1Initial policy creation. One exposure (Main Campus), three named physicians.
Request
{
  "policyStartDate": "2025-01-01",
  "policyEndDate": "2025-12-31",
  "fieldModelV1Data": {
    "policy": {
      "policyStatus": "Active",
      "carrier": "National Indemnity Co",
      "deductible": 25000,
      "aggregateLimit": 5000000,
      "ratingResponse": {
        "annualPremium": 85000,
        "proratedPremium": 85000
      },
      "fullTermPolicyBilling": {
        "policyPremium": 85000,
        "policyTaxes": 4250,
        "policyFees": 500,
        "policyGrandTotal": 89750
      },
      "exposures": [{
        "id": "exp-1",
        "exposureType": "MedicalFacility",
        "facilityName": "Greenfield Main Campus",
        "bedCount": 120,
        "coveredSpecialties": ["Cardiology", "Orthopedics", "General Surgery"],
        "namedPhysicians": ["Dr. Patel", "Dr. Nguyen", "Dr. Hoffman"],
        "ratingResponse": {
          "annualPremium": 85000,
          "proratedPremium": 85000
        }
      }]
    }
  }
}
Segments (1):
#Date RangeStatusExposuresPolicy Annualized Premium
1Jan 1 – Dec 31ActiveMain Campus (120 beds, 3 physicians)85,000
fullTermPolicyBilling: Premium 85,000 · Taxes 4,250 · Fees 500 · Total 89,750With a single full-year segment, the annualized premium matches the billing premium. This won’t last.

​
Endorsements

Effective: Apr 1 · Version: 2A satellite clinic opens April 1. The new exposure is Added to the collection. Rating and billing updated for both segments — the existing Jan–Mar segment needs its prorated premium updated too, since it now covers only 3 months instead of 12.
Deltas
[
  {
    "startDate": "2025-04-01", "endDate": "2025-12-31",
    "path": "policy.exposures",
    "action": "Add",
    "value": {
      "id": "exp-2",
      "exposureType": "OutpatientClinic",
      "facilityName": "Greenfield West Clinic",
      "bedCount": 0,
      "coveredSpecialties": ["Dermatology", "Family Medicine"],
      "namedPhysicians": ["Dr. Kim"],
      "ratingResponse": {
        "annualPremium": 19000,
        "proratedPremium": 14250
      }
    }
  },
  {
    "startDate": "2025-01-01", "endDate": "2025-03-31",
    "path": "policy.ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 85000, "proratedPremium": 21250 }
  },
  {
    "startDate": "2025-01-01", "endDate": "2025-03-31",
    "path": "policy.exposures[exp-1].ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 85000, "proratedPremium": 21250 }
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-12-31",
    "path": "policy.ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 104000, "proratedPremium": 78000 }
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 85000, "proratedPremium": 63750 }
  },
  {
    "startDate": "2025-01-01", "endDate": "2025-12-31",
    "path": "policy.fullTermPolicyBilling",
    "action": "Modify",
    "value": {
      "policyPremium": 98000,
      "policyTaxes": 4900,
      "policyFees": 500,
      "policyGrandTotal": 103400
    }
  }
]
Segments (2): +1
#Date RangeExposuresPolicy Annualized Premium
1Jan 1 – Mar 31Main Campus85,000
2Apr 1 – Dec 31Main Campus + West Clinic104,000
fullTermPolicyBilling: Premium 98,000 · Taxes 4,900 · Fees 500 · Total 103,400The annualized premiums are 85,000 and 104,000 — neither matches the billing premium of 98,000. The billing total reflects the blended cost across both periods plus a flat surplus lines assessment.
Effective: Jun 1 · Version: 3A new surgeon (Dr. Okafor) joins the main campus June 1. Neurology added as a covered specialty. Both deltas use Add on nested exposure fields. Rating updated for the affected periods.
Deltas
[
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].namedPhysicians",
    "action": "Add",
    "value": "Dr. Okafor"
  },
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].coveredSpecialties",
    "action": "Add",
    "value": "Neurology"
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-05-31",
    "path": "policy.ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 104000, "proratedPremium": 17300 }
  },
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 118000, "proratedPremium": 68800 }
  },
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 96000, "proratedPremium": 55700 }
  },
  {
    "startDate": "2025-01-01", "endDate": "2025-12-31",
    "path": "policy.fullTermPolicyBilling",
    "action": "Modify",
    "value": {
      "policyPremium": 106000,
      "policyTaxes": 5300,
      "policyFees": 500,
      "policyGrandTotal": 111800
    }
  }
]
Segments (3): +1
#Date RangePhysiciansSpecialtiesPolicy Annualized Premium
1Jan 1 – Mar 31Patel, Nguyen, HoffmanCardiology, Orthopedics, Surgery85,000
2Apr 1 – May 31Patel, Nguyen, HoffmanCardiology, Orthopedics, Surgery104,000
3Jun 1 – Dec 31Patel, Nguyen, Hoffman, OkaforCardiology, Orthopedics, Surgery, Neurology118,000
fullTermPolicyBilling: Premium 106,000 · Taxes 5,300 · Fees 500 · Total 111,800The Apr–Dec segment from version 2 split at the June boundary. Three different annualized rates (85k, 104k, 118k) but a single billing premium of 106k.
Effective: Jun 1 · Version: 4Dr. Nguyen leaves the practice effective June 1. 10 beds decommissioned. Uses Remove on a primitive collection and Modify on a scalar.
Deltas
[
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].namedPhysicians",
    "action": "Remove",
    "value": "Dr. Nguyen"
  },
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].bedCount",
    "action": "Modify",
    "value": 110
  },
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 112000, "proratedPremium": 65000 }
  },
  {
    "startDate": "2025-06-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 93000, "proratedPremium": 53900 }
  },
  {
    "startDate": "2025-01-01", "endDate": "2025-12-31",
    "path": "policy.fullTermPolicyBilling",
    "action": "Modify",
    "value": {
      "policyPremium": 101000,
      "policyTaxes": 5050,
      "policyFees": 500,
      "policyGrandTotal": 106550
    }
  }
]
Segments (3): unchanged
#Date RangeBedsPhysiciansPolicy Annualized Premium
1Jan 1 – Mar 31120Patel, Nguyen, Hoffman85,000
2Apr 1 – May 31120Patel, Nguyen, Hoffman104,000
3Jun 1 – Dec 31110Patel, Hoffman, Okafor112,000
fullTermPolicyBilling: Premium 101,000 · Taxes 5,050 · Fees 500 · Total 106,550Same segment count — the boundaries didn’t move, only the Jun–Dec data and rate changed. The annualized rate dropped from 118k to 112k reflecting fewer beds and one fewer physician.
Effective: Apr 1 · Version: 5Internal audit reveals the bed decommissioning actually happened in April, not June. Dr. Nguyen’s departure was also effective April 1. Dr. Okafor started in April too. Retroactive corrections applied.
Deltas
[
  {
    "startDate": "2025-04-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].bedCount",
    "action": "Modify",
    "value": 110
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].namedPhysicians",
    "action": "Remove",
    "value": "Dr. Nguyen"
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].namedPhysicians",
    "action": "Add",
    "value": "Dr. Okafor"
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-05-31",
    "path": "policy.ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 108000, "proratedPremium": 18400 }
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-05-31",
    "path": "policy.exposures[exp-1].ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 89000, "proratedPremium": 15100 }
  },
  {
    "startDate": "2025-01-01", "endDate": "2025-12-31",
    "path": "policy.fullTermPolicyBilling",
    "action": "Modify",
    "value": {
      "policyPremium": 100000,
      "policyTaxes": 5000,
      "policyFees": 500,
      "policyGrandTotal": 105500
    }
  }
]
Segments (3): unchanged
#Date RangeBedsPhysiciansSpecialtiesPolicy Annualized Premium
1Jan 1 – Mar 31120Patel, Nguyen, HoffmanCardiology, Orthopedics, Surgery85,000
2Apr 1 – May 31110Patel, Hoffman, OkaforCardiology, Orthopedics, Surgery108,000
3Jun 1 – Dec 31110Patel, Hoffman, OkaforCardiology, Orthopedics, Surgery, Neurology112,000
fullTermPolicyBilling: Premium 100,000 · Taxes 5,000 · Fees 500 · Total 105,500The structural deltas span Apr 1 – Dec 31, but the Jun–Dec segment already had beds=110, Nguyen removed, and Okafor present — no-ops there. Only Apr–May changed. Segment 2’s annualized rate is 108,000 (vs segment 3’s 112,000) because it lacks Neurology.
Setup for what’s next: Segments 2 and 3 now share the same beds, physicians, and exposures. They differ only in whether Neurology is a covered specialty — which also produces different annualized rates (108k vs 112k). One more endorsement that adds Neurology to segment 2 will converge both the structural data and the rating.
Effective: Apr 1 · Version: 6Neurology coverage was contractually effective from the clinic opening date (April 1), not June 1 as originally recorded. Correction applied retroactively.
Deltas
[
  {
    "startDate": "2025-04-01", "endDate": "2025-12-31",
    "path": "policy.exposures[exp-1].coveredSpecialties",
    "action": "Add",
    "value": "Neurology"
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-05-31",
    "path": "policy.ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 112000, "proratedPremium": 19000 }
  },
  {
    "startDate": "2025-04-01", "endDate": "2025-05-31",
    "path": "policy.exposures[exp-1].ratingResponse",
    "action": "Modify",
    "value": { "annualPremium": 93000, "proratedPremium": 15800 }
  },
  {
    "startDate": "2025-01-01", "endDate": "2025-12-31",
    "path": "policy.fullTermPolicyBilling",
    "action": "Modify",
    "value": {
      "policyPremium": 101000,
      "policyTaxes": 5050,
      "policyFees": 500,
      "policyGrandTotal": 106550
    }
  }
]
The Neurology delta adds it to Apr–May. Jun–Dec already has Neurology — no-op. The rating delta updates Apr–May’s annualized rate from 108,000 to 112,000 to match Jun–Dec.After applying, segments 2 and 3 have identical per-segment state — same structural data, same rating. The system merges them.Segments (2): -1
#Date RangeExposuresSpecialtiesPolicy Annualized Premium
1Jan 1 – Mar 31Main CampusCardiology, Orthopedics, Surgery85,000
2Apr 1 – Dec 31Main Campus + West ClinicCardiology, Orthopedics, Surgery, Neurology112,000
fullTermPolicyBilling: Premium 101,000 · Taxes 5,050 · Fees 500 · Total 106,550
Key insight — endorsements can reduce segments. This is not an undo. Six separate transactions produced only 2 segments. The Apr–May / Jun–Dec boundary was erased because corrections converged both the structural data and the rating on both sides. The annualized rates are 85k and 112k — the billing premium of 101k reflects neither.

​
Cancellation and Reinstatement

Effective: Sep 1 · Version: 7Greenfield is acquired by a hospital network with its own coverage. Policy cancelled effective September 1. The system generates the policyStatus delta internally — the caller only provides the cancellation date and updated billing.
Request
{
  "policyId": "550e8400-e29b-41d4-a716-446655440001",
  "cancellationDate": "2025-09-01",
  "deltas": [
    {
      "path": "fullTermPolicyBilling",
      "value": {
        "policyPremium": 72000,
        "policyTaxes": 3600,
        "policyFees": 500,
        "policyGrandTotal": 76100
      }
    }
  ]
}
Cancel and reinstate use a simpler delta format — just path and value, no startDate/endDate/action. The system handles the date ranges and status change internally.
Segments (3): +1
#Date RangeStatusExposuresPolicy Annualized Premium
1Jan 1 – Mar 31ActiveMain Campus85,000
2Apr 1 – Aug 31ActiveMain Campus + West Clinic112,000
3Sep 1 – Dec 31CancelledMain Campus + West Clinic112,000
fullTermPolicyBilling: Premium 72,000 · Taxes 3,600 · Fees 500 · Total 76,100The Apr–Dec segment split at September. The annualized rate stays 112,000 in both segments — the underlying risk profile didn’t change, only the status. But the billing dropped to 72,000 reflecting the shortened coverage period.
Effective: Sep 1 · Version: 8The acquisition falls through. Policy reinstated at the same effective date as the cancellation. A 250 reinstatement fee is added.
Request
{
  "policyId": "550e8400-e29b-41d4-a716-446655440001",
  "reinstatementDate": "2025-09-01",
  "deltas": [
    {
      "path": "fullTermPolicyBilling",
      "value": {
        "policyPremium": 101000,
        "policyTaxes": 5050,
        "policyFees": 750,
        "policyGrandTotal": 106800
      }
    }
  ]
}
Segment 3 returns to "Active" — now identical per-segment state to segment 2. They merge.Segments (2): -1
#Date RangeStatusExposuresPolicy Annualized Premium
1Jan 1 – Mar 31ActiveMain Campus85,000
2Apr 1 – Dec 31ActiveMain Campus + West Clinic112,000
fullTermPolicyBilling: Premium 101,000 · Taxes 5,050 · Fees 750 (was 500) · Total 106,800
Cancel + Reinstate are invisible in the segments. Both transactions are preserved in the audit trail, but the per-segment state is identical to version 6 (pre-cancellation). Only fullTermPolicyBilling changed — the reinstatement fee increased fees from 500 to 750. This is the second type of segment reduction: reversal, where an action directly undoes a prior change’s per-segment effects.

​
Transaction Deletion

Version: 9The acquisition is back on. The reinstatement was premature — delete it.Transaction deletion removes the most recent transaction (the REINSTATE) and recomputes segments from the prior state. The deleted transaction is archived for audit purposes.The result is identical to version 7 (the CANCEL version):Segments (3): +1
#Date RangeStatusExposuresPolicy Annualized Premium
1Jan 1 – Mar 31ActiveMain Campus85,000
2Apr 1 – Aug 31ActiveMain Campus + West Clinic112,000
3Sep 1 – Dec 31CancelledMain Campus + West Clinic112,000
fullTermPolicyBilling: Premium 72,000 · Taxes 3,600 · Fees 500 · Total 76,100The deleted transaction still exists in the audit trail — it’s archived, not erased. But the live policy state has reverted to the cancelled state, including the pre-reinstatement billing.

​
Summary

​
Segment Count Over Time

VersionTransactionDescriptionSegmentsChange
1NEW_BUSINESSInitial policy1—
2ENDORSEAdd clinic2+1
3ENDORSEAdd physician + specialty from Jun3+1
4ENDORSERemove physician, reduce beds from Jun3—
5ENDORSEBackdate corrections to Apr3—
6ENDORSERetroactive Neurology to Apr2-1
7CANCELCancellation from Sep3+1
8REINSTATEReinstatement from Sep2-1
9DELETEUndo reinstatement3+1

​
Two Types of Segment Reduction

Convergence (Version 6)

Retroactive corrections made the Apr–May segment identical to the Jun–Dec segment — both structurally and in rating. Adjacent identical segments merged.Segments can reduce through normal business operations — corrections, reconciliations, and backdated adjustments that happen to converge per-segment state across a boundary.

Reversal (Version 8)

Reinstatement undid the cancellation, making Sep–Dec identical to Apr–Aug. Adjacent identical segments merged.An action that inverts a prior change can collapse the segments that action created — but the audit trail preserves both transactions.

​
Key Takeaways

Transactions are authored. Policy state is derived. Segments are compressed representations of per-segment state.Segment count may increase, decrease, or stay the same with each transaction — independently of whether a change was added, corrected, or reversed. fullTermPolicyBilling and other cross-segment invariants do not affect segment boundaries at all — only per-segment data (including per-segment rating) drives merging.