Skip to main content
This page explains the core data model behind the transaction-based Policy API. Understanding these concepts will help you predict how the API behaves when you create, endorse, cancel, and reinstate policies.

​
Transaction Model

Every change to a policy is recorded as an immutable transaction. Transactions are the single source of truth — policy state is always derived from them, never authored directly.
1

Configure

Define your fields, option sets, and exposure types via the Configuration API.
2

Create

POST /transaction/new-business creates a policy with initial state covering the full term.
3

Endorse

POST /{policyId}/transaction/endorse modifies the policy — add exposures, change field values, adjust coverage periods.
4

Cancel

POST /{policyId}/transaction/cancel cancels the policy from a specified date.
5

Reinstate

POST /{policyId}/transaction/reinstate reinstates a cancelled policy.
6

Renew

POST /transaction/renew starts a new policy term.

​
Transaction Types

NEW_BUSINESS

Creates the policy. The effective date is the policy start date. Produces one segment covering the full term.

ENDORSE

Modifies policy state from a given effective date. May split existing segments or merge them if the change aligns state across periods.

CANCEL

Cancels the policy from the cancellation date. The policy term ends at the cancellation date.

REINSTATE

Reverses a cancellation. The policy term is restored to its pre-cancellation state.

RENEW

Creates a new term for an existing policy. The effective date is the new term start date.

​
Effective Date vs Transaction Timestamp

Each transaction has two timestamps:
  • effectiveDate — when the policy state changes. For an endorsement, this is when the new coverage begins. For a cancellation, this is when coverage ends.
  • transactionTimestamp — when the business decision was made. Defaults to the current time, but can be set explicitly for imports (e.g., aligning to a bordereau booking date).

​
Segments

A segment is a maximal contiguous date range where the policy state is identical.
Segments are NOT one-to-one with transactions. Multiple transactions may produce fewer segments than you expect. A single endorsement may split one segment into many. Corrections can merge segments back together.

​
Segment Properties

  • No overlapping segments within a version
  • Full coverage of the policy period — no gaps
  • No adjacent identical segments — automatically merged

​
How Segments Change

A new policy starts with one segment covering the full term.
[Jan 1 ─────────────────── Dec 31]  State A
This is the key insight: segments reflect the final state of the policy, not its change history. The transaction history preserves the full audit trail.

​
Versions

Each transaction produces a new policy version. A version is a complete snapshot — it contains the full set of segments for the policy at that point in the transaction history.
PropertyDescription
policyVersionSequential version number (1, 2, 3, …)
transactionIdThe transaction that produced this version
segmentsComplete set of segments for this version
startDate / endDatePolicy term boundaries
You can query any historical version to see what the policy looked like after a specific transaction.

​
How It Works

When you submit a transaction, the system:
  1. Loads the previous version — gets the current segments
  2. Applies changes — applies the transaction’s field changes to the affected date ranges
  3. Normalizes — produces deterministic JSON and computes a hash for each resulting segment
  4. Merges — collapses adjacent segments with identical hashes into one
  5. Persists — stores the new version with its segments
You don’t need to understand the internal algorithm to use the API — just know that the system automatically handles segment splitting and merging based on the changes you submit.

​
Premiums and Rating

The API does not calculate premiums. When you submit a transaction, you supply the per-segment field values (including annualPremium) and the fullTermPolicyBilling aggregates yourself. The system stores what you send — it does not pro-rate or re-aggregate.When using the application UI (not headless) with a rater configured, a special aggregation rater automatically computes the fullTermPolicyBilling totals across segments. Through the API, this is your responsibility.

​
Worked Example: Segment Merging

A medical facility policy for Jan 1 – Dec 31 with one exposure (Main Hospital, 120 beds). In each step, the API caller supplies the segment field values and fullTerm aggregates. 
[Jan 1 ─────────────────────────── Dec 31]
annualPremium: $85,000
Exposures: Main Hospital (120 beds)
fullTermPolicyBilling: policyPremium = $85,000Result: 1 segment covering the full year.
The caller submits an endorsement effective April 1 that adds a satellite clinic and sets the new annualPremium for the Apr–Dec period. The caller also updates fullTermPolicyBilling with the pro-rated total.
[Jan 1 ────── Mar 31]                [Apr 1 ────────── Dec 31]
annualPremium: $85,000                annualPremium: $136,000
Exposures: Main Hospital (120 beds)   Exposures: Main Hospital (120 beds)
                                                 + Satellite Clinic (40 beds)
fullTermPolicyBilling: policyPremium = $123,250 (caller-supplied)Result: 2 segments with different premiums and different exposure lists.
The caller submits a retroactive correction backdating the satellite clinic to Jan 1, setting annualPremium to $136,000 for the full year. Since both periods now have identical state, the segments merge.
[Jan 1 ─────────────────────────── Dec 31]
annualPremium: $136,000
Exposures: Main Hospital (120 beds) + Satellite Clinic (40 beds)
fullTermPolicyBilling: policyPremium = $136,000 (caller-supplied)Result: 1 segment. Premium increased from 123,250to123,250 to 136,000 because the satellite clinic is now covered for the full year.
Three transactions, one segment. The audit trail preserves all three transactions, but the derived state is a single uniform segment.

​
Worked Example: Out-of-Order Endorsement

Starting from the merged state above (1 segment, $136k, 2 exposures), a backdated endorsement arrives.
The caller submits an endorsement effective August 1 increasing Main Hospital bed count from 120 to 150, with a new annualPremium for the Aug–Dec period and an updated fullTermPolicyBilling total.
[Jan 1 ────────── Jul 31]            [Aug 1 ────────── Dec 31]
annualPremium: $136,000               annualPremium: $148,000
Main Hospital: 120 beds               Main Hospital: 150 beds
Satellite Clinic: 40 beds             Satellite Clinic: 40 beds
fullTermPolicyBilling: policyPremium = $141,000 (caller-supplied)Result: 2 segments. The backdated endorsement splits the previously merged segment because the Aug–Dec state now differs from Jan–Jul.
Backdated endorsements don’t need special handling — the system applies the changes to the correct date range and recomputes segments automatically. The result is the same whether the endorsement was entered in chronological order or out of order.

​
Transaction Deletion

Only the most recent transaction on a policy can be deleted. Deleting a transaction:
  • Produces a new version derived from the prior transaction’s state
  • Preserves the audit trail — the deleted transaction is archived, not erased
  • Is irreversible through the API once deleted (the transaction can be re-created manually)
Transaction deletion undoes the most recent change. It does not allow arbitrary transaction removal from the middle of the history.