Overview - AI Insurance

The Policies API allows you to manage policies for your company. Policies represent the insurance contracts that have been issued. Key Concepts:

Policies are insurance contracts issued to insureds
Each policy has a number, primary insured, and effective dates
Policies are divided into segments when exposures change mid-term
Policies can be created directly for historical imports, or via the quote→bind flow
Results are paginated with a fixed page size of 50

API Endpoints

List Policies - Retrieve paginated list of policies with filtering and sorting
Get Policy - Retrieve detailed policy information including segments, coverages, and rating inputs
Create Policy - Create a policy directly (for historical imports)
Delete Policy - Soft delete a policy by ID

Policy Segments

When exposures (insureds) are added, removed, or modified mid-term, policies are automatically divided into segments. Each segment represents a period where policy data is constant. Example: A policy running from Jan 1 to Dec 31 has one exposure. On June 1, a second exposure is added. The policy will have two segments:

Segment 1: Jan 1 - May 31 (one exposure)
Segment 2: Jun 1 - Dec 31 (two exposures)

Each segment includes:

Date range (start, end)
Status (bound, quoted, cancelled)
Premium and base premium totals
Full coverage details with limits
Exposure-level rating inputs showing how premiums were calculated

Time Travel (Historical Views)

The Get Policy endpoint supports the asOf query parameter to retrieve the policy state as it existed at a specific point in time:

GET /api/external/companies/{companyId}/policies/{policyId}?asOf=2024-06-15T10:00:00Z

This is useful for:

Auditing: Understanding the policy state at a specific date
Reporting: Generating historical reports
Debugging: Seeing how the policy looked before endorsements

Creating Policies

The Create Policy endpoint is primarily designed for historical imports where policies need to be created without going through the standard quote→bind wizard flow. Workflow:

Create insureds first via POST /insureds
(Optional) Create broker via POST /brokers if policy has a broker
Create the policy with insured and broker references via POST /policies
The endpoint automatically creates insured snapshots with the provided ratingInfo

Required Fields

Field	Type	Description
`referenceId`	string	Policy number (must be unique per company)
`startsAtDate`	date	Policy effective start date (YYYY-MM-DD)
`endsAtDate`	date	Policy effective end date (YYYY-MM-DD)
`type`	string	Policy type (C, N, T, O, P, S, Q, R, A)
`billingPeriod`	string	Billing frequency (annual, quarterly, monthly, etc.)
`exposures`	array	At least one exposure with exactly one role “primary”
`coverages`	array	At least one coverage with valid coverageTypeId

Optional Fields

Field	Type	Description
`coverageTimezone`	string	IANA timezone (defaults to company default)
`description`	string	Policy description
`premium`	number	Premium in cents (overrides rating calculation)
`brokerId`	uuid	ID of existing broker (use `POST /brokers` first)

Policy Types

Code	Description
C	Claims Made
N	New Claims Made
T	Tail
O	Occurrence
P	Occurrence + Claims Made
S	Split (Half Claims Made/Occurrence)
Q	Quota Share
R	Occurrence + Claims Made + Tail
A	Claims Made (Alternative)

Policy Fields (List Response)

Field	Type	Description
`id`	uuid	Policy identifier
`companyId`	uuid	Company identifier
`number`	string	Policy number
`createdAt`	datetime	When the policy was created (ISO 8601)
`primaryInsuredId`	uuid/null	ID of the primary insured on this policy

Policy Fields (Get Response)

The Get Policy endpoint returns detailed information including all list fields plus:

Field	Type	Description
`policyId`	uuid	Policy identifier (same as `id`)
`policyNumber`	string/null	Policy number (same as `referenceId`)
`referenceId`	string/null	Policy reference ID
`startsAtDate`	date/null	Policy effective start date
`endsAtDate`	date/null	Policy effective end date
`status`	string	Current policy status (see below)
`termStart`	date/null	Policy term start date
`termEnd`	date/null	Policy term end date
`sourceTransactionId`	uuid/null	Transaction that created/modified the policy
`effectiveTimestamp`	datetime/null	When current state became effective
`segments`	array	Policy segments with coverage and exposure details
`type`	string/null	Policy type code (C, N, T, O, etc.)
`description`	string/null	Policy description
`coverageTimezone`	string/null	IANA timezone for coverage dates
`currencyCode`	string/null	ISO 4217 currency code (e.g., “USD”)
`prevPolicyId`	uuid/null	ID of previous policy (for renewal chains)
`cancelledAt`	datetime/null	Timestamp when policy was cancelled
`brokerId`	string/null	ID of the broker associated with this policy
`recipientName`	string/null	Name of the policy recipient
`recipientEmail`	string/null	Email of the policy recipient
`primaryInsuredName`	string/null	Name of the primary insured
`cancellationReason`	string/null	Reason for policy cancellation
`cancellationExplanation`	string/null	Additional cancellation explanation

Policy Status Values

Status	Description
`active`	Policy is currently in effect
`not_started`	Policy start date is in the future
`expired`	Policy end date is in the past
`pending_signature`	Awaiting policyholder signature
`pending_payment`	Awaiting payment
`pending_actions`	Awaiting both signature and payment
`pending_renewal`	Within 60 days of renewal date
`renewal_in_progress`	Renewal submission created but not bound
`renewed`	Policy has been renewed
`cancelled`	Policy has been cancelled

Segment Fields

Each segment in the segments array contains:

Field	Type	Description
`start`	date	Segment start date
`end`	date	Segment end date
`status`	string	Segment status (`bound`, `quoted`, `cancelled`)
`premium`	number/null	Total premium for segment (cents)
`basePremium`	number/null	Base premium before adjustments (cents)
`coverages`	array	Coverages active during this segment
`exposures`	array	Exposures with premium breakdown and rating inputs

Exposure Fields

Each exposure in a segment contains:

Field	Type	Description
`exposureId`	uuid	Exposure (insured) identifier
`exposureType`	string/null	Type of exposure (e.g., “company”, “distribution_center”)
`premium`	number/null	Premium for this exposure (cents)
`basePremium`	number/null	Base premium before adjustments (cents)
`ratingInputs`	object/null	Rating factors by coverage type (see below)

Rating Inputs Structure

The ratingInputs object is keyed by coverage type ID. Each coverage contains rating factor objects with:

Field	Type	Description
`fieldName`	string	Human-readable factor name
`adjustedPremium`	number	Premium after factor applied
`multiplier`	number/array	Multiplier value(s)
`value`	number/array	Base value(s) used
`days`	integer	Days for pro-rata calculations
`base`	integer	Base days (typically 365)

Filtering and Sorting

Filter Parameters

Parameter	Type	Description
`primaryInsuredId`	uuid	Filter by primary insured ID
`filterText`	string	Text search across policy number and other fields

Sorting Parameters

Parameter	Type	Default	Description
`sortBy`	string	`createdAt`	Field to sort by (`createdAt`, `updatedAt`, `number`, `startsAtDate`, `endsAtDate`)
`sortDirection`	string	`desc`	Sort direction (`asc` or `desc`)

Pagination

Parameter	Type	Default	Description
`page`	integer	1	Page number (1-based, page size 50)

Response includes:

items - Array of policies for the current page
totalCount - Total number of matching policies across all pages

Permissions

Access to policies requires the appropriate permissions based on your API key:

Operation	Required Permission
List Policies	`company.policy:read`
Get Policy	`company.policy:read`
Create Policy	`company.policy:create`
Delete Policy	`policy:delete`

Example: Create Policy Request

{
  "referenceId": "POL-2025-001",
  "startsAtDate": "2025-01-01",
  "endsAtDate": "2026-01-01",
  "type": "C",
  "billingPeriod": "annual",
  "exposures": [
    {
      "insuredId": "550e8400-e29b-41d4-a716-446655440200",
      "role": "primary",
      "joinDate": "2025-01-01",
      "terminationDate": "2026-01-01",
      "ratingInfo": {
        "revenue": 5000000,
        "employees": 25
      }
    }
  ],
  "coverages": [
    {
      "coverageTypeId": "550e8400-e29b-41d4-a716-446655440300"
    }
  ]
}

Response: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440100"
}

Example: List Policies Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440100",
      "companyId": "550e8400-e29b-41d4-a716-446655440000",
      "number": "POL-2025-001",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440200"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440101",
      "companyId": "550e8400-e29b-41d4-a716-446655440000",
      "number": "POL-2025-002",
      "createdAt": "2025-01-16T14:20:00.000Z",
      "primaryInsuredId": "550e8400-e29b-41d4-a716-446655440201"
    }
  ],
  "totalCount": 42
}

Example: Get Policy Response

{
  "id": "84f9b186-08fc-408a-8f8c-d739e161c423",
  "policyId": "84f9b186-08fc-408a-8f8c-d739e161c423",
  "companyId": "7626bc64-e937-4f52-bb4a-05848bd09860",
  "referenceId": "POL-2025-001",
  "policyNumber": "POL-2025-001",
  "createdAt": "2025-01-19T14:58:29.000+00:00",
  "primaryInsuredId": "c018b789-d235-4597-bf2e-8c308465b890",
  "primaryInsuredName": "Acme Corporation",
  "startsAtDate": "2025-01-19",
  "endsAtDate": "2026-01-19",
  "status": "active",
  "termStart": "2025-01-19",
  "termEnd": "2026-01-19",
  "sourceTransactionId": "61b8357e-f92c-404e-825c-63432974c8a1",
  "effectiveTimestamp": "2025-01-19T15:01:45.000+00:00",
  "type": "C",
  "description": "Professional Liability Policy",
  "coverageTimezone": "America/New_York",
  "currencyCode": "USD",
  "prevPolicyId": null,
  "cancelledAt": null,
  "brokerId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "recipientName": "John Smith",
  "recipientEmail": "john.smith@acme.com",
  "cancellationReason": null,
  "cancellationExplanation": null,
  "segments": [
    {
      "start": "2025-01-19",
      "end": "2025-05-18",
      "status": "bound",
      "premium": 293016,
      "basePremium": 328490,
      "coverages": [
        {
          "id": "d4d4b369-4b4c-4240-bb32-cfce31be99d7",
          "coverageTypeId": "bodily_injury_and_property_damage",
          "coverageTypeName": "Bodily Injury and Property Damage",
          "deductible": 25000,
          "defenseInsideLimit": "outside",
          "limits": [
            {
              "id": "716bf78a-f714-4904-89b6-053b4e7793b7",
              "name": "Each Occurrence",
              "amount": 1000000
            }
          ]
        }
      ],
      "exposures": [
        {
          "exposureId": "c018b789-d235-4597-bf2e-8c308465b890",
          "exposureType": "company",
          "premium": 146508,
          "basePremium": 164245,
          "ratingInputs": {
            "bodily_injury_and_property_damage": {
              "bipdBaseRate": {
                "fieldName": "BIPD Base Rate",
                "multiplier": 46350,
                "adjustedPremium": 46350
              },
              "deductibleMultiplier": {
                "fieldName": "Deductible Multiplier",
                "multiplier": 0.7,
                "adjustedPremium": 32445
              }
            }
          }
        }
      ]
    }
  ]
}

​API Endpoints

​Policy Segments

​Time Travel (Historical Views)

​Creating Policies

​Required Fields

​Optional Fields

​Policy Types

​Policy Fields (List Response)

​Policy Fields (Get Response)

​Policy Status Values

​Segment Fields

​Exposure Fields

​Rating Inputs Structure

​Filtering and Sorting

​Filter Parameters

​Sorting Parameters

​Pagination

​Permissions

​Example: Create Policy Request

​Example: List Policies Response

​Example: Get Policy Response