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.

​
Headless Insurance Program

The Policy API is designed to work 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 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 (coming soon)
POST/v1/policies/{policyId}/transaction/cancelCancel a policy (coming soon)
POST/v1/policies/{policyId}/transaction/reinstateReinstate a cancelled policy (coming soon)
POST/v1/policies/transaction/renewRenew a policy for a new term (coming soon)
DELETE/v1/policies/{policyId}/transactions/{transactionId}Delete most recent transaction (coming soon)

​
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 (coming soon)

​
Reporting

MethodEndpointDescription
GET/v1/policies/bordereauBordereau export (coming soon)
GET/v1/policies/{policyId}/earned-premiumEarned premium calculation (coming soon)

​
Configuration

MethodEndpointDescription
GET/v1/policies/configurationGet field configuration

​
Permissions

OperationPermission
List, Get, Configuration, Historycompany.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
{
  "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

​
Previous CRUD API

The previous CRUD endpoints (POST /v1/policies, DELETE /v1/policies/{policyId}) are deprecated. See Policy CRUD (Deprecated).