Skip to main content
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.
TransactionDescription
New BusinessCreates a new policy with initial state
EndorseModifies an existing policy (add/remove exposures, change fields)
CancelCancels a policy from a given date
ReinstateReinstates a previously cancelled policy
RenewRenews 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 how transactions place changes in time — effectiveDate vs transactionTimestamp, backdating, and booking ahead — see Effective Dates & the Policy Timeline. For a full worked example tracing 9 transactions through a realistic policy lifecycle, see the Lifecycle Walkthrough.

​
API Endpoints

​
Transactions (write)

MethodEndpointDescription
POST/v1/policies/transaction/new-businessCreate a new policy
POST/v1/policies/{policyId}/transaction/endorseEndorse an existing policy
POST/v1/policies/{policyId}/transaction/cancelCancel a policy
POST/v1/policies/{policyId}/transaction/reinstateReinstate a cancelled policy
POST/v1/policies/transaction/renewRenew a policy for a new term
DELETE/v1/policies/{policyId}/transactions/{transactionId}Delete most recent transaction

​
Queries (read)

MethodEndpointDescription
GET/v1/policies/listList policies (latest version per policy, with segment scope filtering)
GET/v1/policies/versionsList policy versions across all policies
GET/v1/policies/{policyId}/versions/{version}Get a specific policy version with segments
GET/v1/policies/{policyId}/versionsList versions for a single policy
GET/v1/policies/{policyId}/transactionsTransaction audit trail
GET/v1/policies/{policyId}/transactions/{transactionId}Get a single transaction with deltas

​
Reporting

MethodEndpointDescription
GET/v1/policies/bordereauList bordereau rows (paginated JSON)
GET/v1/policies/bordereau/downloadDownload bordereau as CSV
POST/v1/policies/bordereau/exportExport bordereau to Google Sheets
GET/v1/policies/{policyId}/earned-premiumEarned premium for a single policy
GET/v1/policies/list/earned-premiumEarned premium for multiple policies
GET/v1/policies/aggregate/earned-premiumAggregate earned premium across policies

​
Validation

MethodEndpointDescription
GET/v1/policies/{policyId}/validateValidate a single policy’s data consistency
GET/v1/policies/validateValidate multiple policies in batch

​
Configuration

MethodEndpointDescription
GET/v1/entities/Policy/configurationGet field configuration

​
Permissions

OperationPermission
List, Get, Configuration, History, Reporting (Earned Premium, Bordereau), Validationcompany.policy:read
New Business, Renewcompany.policy:create
Endorse, Cancel, Reinstatecompany.policy:update
Delete Transactionpolicy:delete

​
Example: Create a Policy

​
Request

POST /v1/policies/transaction/new-business
{
  "fieldModelV1Data": {
    "policy": {
      "policyStatus": "active",
      "annualPremium": 85000,
      "fullTermPolicyInfo": {
        "policyStartDate": { "year": 2025, "month": 1, "day": 1, "timezone": "America/New_York" },
        "policyEndDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
        "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010",
        "primaryInsuredName": "Mercy General Hospital"
      },
      "fullTermPolicyBillingInfo": {
        "policyPremium": 85000,
        "policyTaxes": 0,
        "policyFees": 500,
        "policyGrandTotal": 85500
      },
      "additionalExposures": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440011",
          "exposureType": "MedicalFacility",
          "bedCount": 120
        }
      ]
    }
  }
}
There are no top-level date parameters — the policy term comes solely from fullTermPolicyInfo.policyStartDate / policyEndDate.

​
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",
  "fullTermPolicyInfo": {
    "policyStartDate": { "year": 2025, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyEndDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
    "primaryInsuredJoin": "550e8400-e29b-41d4-a716-446655440010",
    "primaryInsuredName": "Mercy General Hospital"
  },
  "fullTermPolicyBillingInfo": {
    "policyPremium": 85000,
    "policyTaxes": 0,
    "policyFees": 500,
    "policyGrandTotal": 85500
  },
  "fullTermPolicyRatingResult": null,
  "segments": [
    {
      "startDate": "2025-01-01",
      "endDate": "2026-01-01",
      "fieldModelV1Data": {
        "policy": {
          "policyStatus": "active",
          "annualPremium": 85000,
          "fullTermPolicyInfo": { "...": "..." },
          "fullTermPolicyBillingInfo": { "...": "..." },
          "additionalExposures": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440011",
              "exposureType": "MedicalFacility",
              "bedCount": 120
            }
          ]
        }
      }
    }
  ]
}

​
Key Points

  • Term bounds come solely from fullTermPolicyInfo.policyStartDate / policyEndDate — there are no top-level date parameters
  • fieldModelV1Data.policy contains all policy-level fields — including any embedded exposure fields your configuration defines (e.g. primaryInsured / additionalExposures in the default configuration). Their shape is whatever your tenant configuration says; they are validated per-field like any other field. From those embedded values the framework-required referencedExposures calculated field derives the flat list of Exposure ids the policy references — see Referenced Exposures
  • policyStatus ("active" / "cancelled") is a segment-scoped policy field — not part of fullTermPolicyInfo
  • fullTermPolicyInfo is required on every policy and must carry the primary-insured identity: primaryInsuredJoin (the UUID of an existing Exposure — create it first via the Exposures API) and primaryInsuredName (its display name). These two fields are the only exposure-related values the platform itself requires
  • fullTermPolicyBillingInfo is optional (a policy may carry no billing info); fullTermPolicyRatingResult is optional
  • transactionTimestamp is optional — defaults to the current time if omitted. When set explicitly on a later transaction it must be >= the latest already on the policy (the audit axis only moves forward); effective dates may still backdate freely. See Effective Dates & the Policy Timeline
  • A transaction’s effectiveDate must fall within the term (policyStartDate <= effectiveDate <= policyEndDate) — outside the term it is rejected with 400. For how effectiveDate relates to transactionTimestamp and to each delta’s startDate, see Effective Dates & the Policy Timeline