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

# Basic Policies Overview

> Simple flat-shape CRUD for policies that don't need transaction history

The Basic Policies API is a **simplified way of managing policies in the app** — flat-shape CRUD over policies with company-configured dynamic fields. Use it when you don't need the temporal versioning, segments, or earned-premium calculations of the [transaction-based Policy API](/api-v1-reference/policies/overview).

**Key Concepts:**

* Fields are **dynamically defined** per company. Use the [Configuration endpoint](#configuration) to discover available fields and their types.
* The request body for create is a **flat JSON object** where keys are field `referenceId`s (e.g., `policyNumber`, `policyStartDate`, `policyType`).
* Exposures are **nested inline** in the policy — each exposure is an object in the `exposures` array, with an `id` referencing an existing exposure record.
* Responses include a `fieldModelV1Data` object containing all field values plus the nested `exposures` array.

***

## When to use Basic vs Transaction-Based Policies

| Use case                                                                                          | API                                                               |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Simple data ingestion, policies that won't be modified after creation, no audit trail needed      | **Basic Policies**                                                |
| Endorsements, cancellations, reinstatements, renewals, earned-premium reporting, full audit trail | [Transaction-Based Policies](/api-v1-reference/policies/overview) |

Both APIs share the same underlying storage and configuration — they're alternative write paths over the same policy records.

***

## Configuration

Call [`GET /v1/policies/configuration`](/api-reference/field-model-policies/get-policies-configuration) to get a JSON Schema of the available policy and exposure fields for your company. The same endpoint drives both the Basic and the Transaction-Based Policy APIs — one configuration, shared across both.

***

## API Endpoints

* **Get Configuration** — `GET /v1/policies/configuration`
* **Create Policy** — `POST /v1/policies`
* **Bind Quote to Create Policy** — `POST /v1/quotes/{quoteId}/bind` (creates a Basic Policy from an existing quote)
* **List Policies** — `GET /v1/policies` with filtering, sorting, pagination
* **Get Policy** — `GET /v1/policies/{policyId}`
* **Delete Policy** — `DELETE /v1/policies/{policyId}` (soft delete)

***

## Permissions

| Operation         | Required Permission     |
| ----------------- | ----------------------- |
| Get Configuration | `company.policy:read`   |
| List Policies     | `company.policy:read`   |
| Get Policy        | `company.policy:read`   |
| Create Policy     | `company.policy:create` |
| Bind Quote        | `company.quote:create`  |
| Delete Policy     | `policy:delete`         |

***

## Filtering

| Parameter                | Type                       | Description                                                                                                                                                 |
| ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                     | `string` or `string[]`     | Filter by policy ID (single or array).                                                                                                                      |
| `policyNumberFilterText` | `string`                   | Case-insensitive substring match against `policyNumber` only. Does not search any other field.                                                              |
| `filters`                | `FieldModelV1ListFilter[]` | Structured per-field filters against any FMV1 field or system column. Combined with AND semantics. See [Filters](#filters-structured-field-matching) below. |

### Filters: structured field matching

Each item in `filters` is an object with `fieldReferenceId`, `fieldType`, `operator`, and a `value` (plus `valueTo` for `between` operators and `systemColumn` for `systemUser` / `systemDate`). The set of operators and the shape of `value` depend on `fieldType`.

Supported field types and their operators:

| `fieldType`                               | Operators                                      | `value` shape                                                       |
| ----------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------- |
| `text`                                    | `matches`, `contains`, `doesNotContain`        | string                                                              |
| `optionSet`                               | `in`                                           | string\[] (allowed option keys)                                     |
| `number`                                  | `equals`, `greaterThan`, `lessThan`, `between` | number (+ `valueTo` for `between`)                                  |
| `boolean`                                 | `equals`                                       | boolean                                                             |
| `date`                                    | `on`, `before`, `after`, `between`             | `{ year, month, day }` (+ `valueTo` for `between`)                  |
| `currency`                                | `equals`, `greaterThan`, `lessThan`, `between` | number (+ `valueTo` for `between`)                                  |
| `address`                                 | `contains`                                     | string (substring across street/city/state/zip)                     |
| `join`                                    | `in`                                           | string\[] (allowed linked-entity IDs)                               |
| `textList` / `numberList` / `addressList` | `listIncludes`                                 | one item value of the list element type                             |
| `optionSetList`                           | `listIn`, `listAll`, `listExcludes`            | string\[]                                                           |
| `systemUser`                              | `in`                                           | string\[] + `systemColumn: "createdBy" \| "updatedBy"`              |
| `systemDate`                              | `on`, `before`, `after`, `between`             | `{ year, month, day }` + `systemColumn: "createdAt" \| "updatedAt"` |

Example: policies created after Jan 1 2026 whose `policyStatus` is `active`:

```json theme={null}
[
  {
    "fieldReferenceId": "policyStatus",
    "fieldType": "optionSet",
    "operator": "in",
    "value": ["active"]
  },
  {
    "fieldReferenceId": "createdAt",
    "fieldType": "systemDate",
    "operator": "after",
    "value": { "year": 2026, "month": 1, "day": 1 },
    "systemColumn": "createdAt"
  }
]
```

***

## Sorting

| Value       | Description                     |
| ----------- | ------------------------------- |
| `createdAt` | Sort by creation date (default) |
| `updatedAt` | Sort by last update date        |
| `number`    | Sort by policy number           |

Use the `sortDirection` parameter (`asc` or `desc`) to control sort order.

***

## Example Create Request

Before creating a policy, create any exposures it references via the [Exposures API](/api-v1-reference/exposures/overview) — `primaryInsured` and each entry in `exposures[].id` must point to an existing exposure record.

```json theme={null}
{
  "policyNumber": "POL-2026-0001",
  "policyStartDate": { "date": "2026-01-01", "timezone": "America/New_York" },
  "policyEndDate": { "date": "2027-01-01", "timezone": "America/New_York" },
  "policyEffectiveDate": { "date": "2026-01-01", "timezone": "America/New_York" },
  "policyType": "generalLiability",
  "policyTimeZone": "America/New_York",
  "primaryInsured": "550e8400-e29b-41d4-a716-446655440010",
  "exposures": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "exposureName": "Acme Corporation",
      "exposureType": "business"
    }
  ]
}
```

Additional company-configured fields (custom text, number, option-set, or object fields defined in your FMV1 configuration) may be included alongside the standard fields above.

### 201 Created

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

## Example Get Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "companyId": "550e8400-e29b-41d4-a716-446655440000",
  "fieldModelV1Data": {
    "policyNumber": "POL-2026-0001",
    "policyStartDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyEndDate": { "year": 2027, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyEffectiveDate": { "year": 2026, "month": 1, "day": 1, "timezone": "America/New_York" },
    "policyType": "generalLiability",
    "policyTimeZone": "America/New_York",
    "primaryInsured": "550e8400-e29b-41d4-a716-446655440010",
    "exposures": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "exposureName": "Acme Corporation",
        "exposureType": "business"
      }
    ]
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": null,
  "createdBy": "google-oauth2|123456789",
  "updatedBy": null
}
```

Date-typed fields (`policyStartDate`, `policyEndDate`, `policyEffectiveDate`) are canonicalized on write from the `{ date: "YYYY-MM-DD", timezone }` input form to the internal `{ day, month, year, timezone }` form shown in responses.