Overview

Transaction-based policy management with temporal versioning

The FMV1 Policy API manages policies through immutable transactions. Each transaction (new business, endorsement, cancellation, reinstatement, renewal) produces a new policy version with a complete set of time-based segments.

Configuration-Driven

The Policy API works with the Configuration API. The same field definitions you configure — policy fields, exposure fields, option sets — are the fields you write when creating policies through transactions.

1. Configure your insurance program — define fields, option sets, exposure types
2. Create policies via POST /transaction/new-business
3. Manage the lifecycle — endorse, cancel, reinstate, renew
4. Query state — get a policy at any point in time, see full audit trail

Core Concepts

Transactions

Policies are modified through immutable transactions. Each transaction records what changed and produces a new policy version.

Transaction	Description
New Business	Creates a new policy with initial state
Endorse	Modifies an existing policy (add/remove exposures, change fields)
Cancel	Cancels a policy from a given date
Reinstate	Reinstates a previously cancelled policy
Renew	Renews a policy for a new term

Segments

A segment is a date range where policy state is identical. Segments are derived from final state — they are not one-to-one with transactions. Adjacent segments with identical data are automatically merged.

For example, three transactions can produce a single segment if the net effect returns the policy to a uniform state across the term.

Versions

Each transaction produces a new version with a complete set of segments representing the full policy timeline. You can query any historical version.

For a deeper explanation of these concepts, see Concepts. For a full worked example tracing 9 transactions through a realistic policy lifecycle, see the Lifecycle Walkthrough.

API Endpoints

Transactions (write)

Method	Endpoint	Description
POST	/v1/policies/transaction/new-business	Create a new policy
POST	/v1/policies/{policyId}/transaction/endorse	Endorse an existing policy
POST	/v1/policies/{policyId}/transaction/cancel	Cancel a policy
POST	/v1/policies/{policyId}/transaction/reinstate	Reinstate a cancelled policy
POST	/v1/policies/transaction/renew	Renew a policy for a new term
DELETE	/v1/policies/{policyId}/transactions/{transactionId}	Delete most recent transaction

Queries (read)

Method	Endpoint	Description
GET	/v1/policies/list	List policies (latest version per policy, with segment scope filtering)
GET	/v1/policies/versions	List policy versions across all policies
GET	/v1/policies/{policyId}/versions/{version}	Get a specific policy version with segments
GET	/v1/policies/{policyId}/versions	List versions for a single policy
GET	/v1/policies/{policyId}/transactions	Transaction audit trail
GET	/v1/policies/{policyId}/transactions/{transactionId}	Get a single transaction with deltas

Reporting

Method	Endpoint	Description
GET	/v1/policies/bordereau	List bordereau rows (paginated JSON)
GET	/v1/policies/bordereau/download	Download bordereau as CSV
POST	/v1/policies/bordereau/export	Export bordereau to Google Sheets
GET	/v1/policies/{policyId}/earned-premium	Earned premium for a single policy
GET	/v1/policies/list/earned-premium	Earned premium for multiple policies
GET	/v1/policies/aggregate/earned-premium	Aggregate earned premium across policies

Validation

Method	Endpoint	Description
GET	/v1/policies/{policyId}/validate	Validate a single policy’s data consistency
GET	/v1/policies/validate	Validate multiple policies in batch

Configuration

Method	Endpoint	Description
GET	/v1/policies/configuration	Get field configuration

Permissions

Operation	Permission
List, Get, Configuration, History, Reporting (Earned Premium, Bordereau), Validation	company.policy:read
New Business, Renew	company.policy:create
Endorse, Cancel, Reinstate	company.policy:update
Delete Transaction	policy:delete

Example: Create a Policy

Request

POST /v1/policies/transaction/new-business

{
  "policyStartDate": "2025-01-01",
  "policyEndDate": "2026-01-01",
  "fieldModelV1Data": {
    "policy": {
      "annualPremium": 85000,
      "fullTermPolicyInfo": {
        "policyStatus": "active",
        "policyStartDate": { "year": 2025, "month": 1, "day": 1, "timezone": "America/New_York" },
        "policyEndDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
        "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010"
      },
      "fullTermPolicyBilling": {
        "policyPremium": 85000,
        "policyTaxes": 0,
        "policyFees": 500,
        "policyGrandTotal": 85500
      },
      "exposures": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440010",
          "exposureType": "MedicalFacility",
          "bedCount": 120
        }
      ]
    }
  }
}

Response

201 Created

{
  "policyId": "550e8400-e29b-41d4-a716-446655440001",
  "policyVersion": 1,
  "transactionId": "550e8400-e29b-41d4-a716-446655440002",
  "startDate": "2025-01-01",
  "endDate": "2026-01-01",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "fullTermPolicyBilling": {
    "policyPremium": 85000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 85500
  },
  "fullTermPolicyInfo": {
    "policyStatus": "active",
    "policyStartDate": { "year": 2025, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyEndDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
    "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440010"
  },
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2026-01-01",
      "fieldModelV1Data": {
        "policy": {
          "annualPremium": 85000,
          "fullTermPolicyInfo": { "...": "..." },
          "fullTermPolicyBilling": { "...": "..." },
          "exposures": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440010",
              "exposureType": "MedicalFacility",
              "bedCount": 120
            }
          ]
        }
      }
    }
  ]
}

Key Points

• policyStartDate / policyEndDate define the policy term boundaries
• fieldModelV1Data.policy contains all policy-level fields, with exposures nested inside
• fullTermPolicyInfo and fullTermPolicyBilling are required on every policy
• Exposures reference existing exposure records by id — create exposures first via the Exposures API
• transactionTimestamp is optional — defaults to the current time if omitted