> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

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](/api-reference/policies/list-policies)** - Retrieve paginated list of policies with filtering and sorting
* **[Get Policy](/api-reference/policies/get-policy)** - Retrieve detailed policy information including segments, coverages, and rating inputs
* **[Create Policy](/api-reference/policies/create-policy)** - Create a policy directly (for historical imports)
* **[Delete Policy](/api-reference/policies/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:**

1. Create insureds first via `POST /insureds`
2. (Optional) Create broker via `POST /brokers` if policy has a broker
3. Create the policy with insured and broker references via `POST /policies`
4. 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

```json theme={null}
{
  "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`

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440100"
}
```

***

## Example: List Policies Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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
              }
            }
          }
        }
      ]
    }
  ]
}
```

***