> ## 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

> 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](/api-v1-reference/configuration/overview). 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](/api-v1-reference/policies/concepts). For a full worked example tracing 9 transactions through a realistic policy lifecycle, see the [Lifecycle Walkthrough](/api-v1-reference/policies/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

```json POST /v1/policies/transaction/new-business theme={null}
{
  "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

```json 201 Created theme={null}
{
  "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](/api-v1-reference/exposures/overview)
* **`transactionTimestamp`** is optional — defaults to the current time if omitted