> ## 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.
# Data Models
> Reference for all V1 API data structures, field types, and conventions
This page documents the data structures and conventions used across all V1 API endpoints.
***
## Common Conventions
### IDs
All entity identifiers are **UUIDs** (RFC 4122):
```
"550e8400-e29b-41d4-a716-446655440000"
```
### Timestamps
All timestamp fields (`createdAt`, `updatedAt`, `transactionTimestamp`, etc.) are returned as **ISO 8601** strings in UTC:
```
"2026-04-14T10:30:45.123Z"
```
### Dates
Date-only fields (`startDate`, `endDate`, `effectiveDate`, `policyStartDate`, `policyEndDate`) use **ISO 8601 date** format:
```
"2026-01-15"
```
### Nullable Fields
Fields that may be absent are typed as `T | null`. For example, `policyId: string | null` means the field is always present in the response but may be `null`.
***
## Pagination
All list endpoints return the same paginated response shape:
```json theme={null}
{
"items": [],
"totalCount": 0
}
```
| Field | Type | Description |
| ------------ | ------- | --------------------------------------- |
| `items` | array | Entities for the current page |
| `totalCount` | integer | Total matching records across all pages |
**Query parameters** for list endpoints:
| Parameter | Type | Default | Description |
| --------------- | --------------- | ----------- | ---------------------------------- |
| `page` | integer | `1` | 1-based page number |
| `sortBy` | string | `createdAt` | Field to sort by (entity-specific) |
| `sortDirection` | `asc` \| `desc` | `desc` | Sort direction |
Page size is fixed at **50 items per page**.
***
## fieldModelV1Data
Most V1 entities store their custom field data in a `fieldModelV1Data` object. The shape of this object is defined by your company's field configuration — call the entity's `/configuration` endpoint to discover available fields, types, and validation rules.
Keys in `fieldModelV1Data` are **field reference IDs** (the stable identifiers you define when configuring fields).
### Field Value Types
| Field Type | JSON Type | Example |
| ------------------------ | ------------------- | ------------------------------------------------------------------------- |
| Text | `string` | `"Acme Corp"` |
| Number | `number` | `42` |
| Boolean | `boolean` | `true` |
| Date | `object` | `{ "day": 15, "month": 1, "year": 2026, "timezone": "America/New_York" }` |
| Single-select option set | `string` | `"commercial"` |
| Multi-select option set | `array` of `string` | `["general_liability", "property"]` |
### Date Fields
Date fields in `fieldModelV1Data` are represented as objects with individual components:
```json theme={null}
{
"policyEffectiveDate": {
"day": 15,
"month": 1,
"year": 2026,
"timezone": "America/New_York"
}
}
```
| Property | Type | Description |
| ---------- | ------ | ------------------------ |
| `day` | number | Day of the month (1-31) |
| `month` | number | Month (1-12) |
| `year` | number | Four-digit year |
| `timezone` | string | IANA timezone identifier |
API parameters that accept dates directly (such as `policyStartDate`, `effectiveDate`, and other endpoint-level fields) use **ISO 8601 date strings** (`"2026-01-15"`), not the component object format. The component format is specific to custom field data inside `fieldModelV1Data`.
### Option Set Fields
Option set values are stored as **string keys** (not labels). Use the `/configuration` endpoint to map keys to human-readable labels.
**Single-select:**
```json theme={null}
{
"exposureType": "commercial_property"
}
```
**Multi-select:**
```json theme={null}
{
"coverageLines": ["general_liability", "property", "auto"]
}
```
The configuration schema uses `oneOf` to enumerate valid options:
```json theme={null}
{
"exposureType": {
"type": "string",
"title": "exposureType",
"oneOf": [
{ "const": "commercial_property", "title": "Commercial Property" },
{ "const": "residential", "title": "Residential" }
]
}
}
```
***
## Configuration Schema
All entity types have a `/configuration` endpoint that returns a **JSON Schema (Draft 2020-12)** describing valid field data:
```json theme={null}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"fieldReferenceId": {
"type": "string",
"title": "fieldReferenceId",
"format": "date"
}
},
"required": ["fieldReferenceId"]
}
```
### Schema Format Values
The `format` property indicates the semantic type of a field:
| Format | JSON Type | Description | Example Value |
| ----------------- | --------- | ----------------------------- | ----------------------- |
| `date` | `string` | ISO 8601 date | `"2026-01-15"` |
| `email` | `string` | Email address | `"user@example.com"` |
| `phone` | `string` | Phone number | `"+1-555-123-4567"` |
| `currency` | `number` | Monetary amount | `15000` |
| `percent` | `string` | Percentage | `"15.5"` |
| `address` | `string` | Physical address | `"123 Main St, ..."` |
| `entity:exposure` | `string` | Reference to an exposure type | `"commercial_property"` |
***
## Entities
### Exposure
Exposures represent insured entities (e.g., a building, vehicle, or healthcare provider).
| Field | Type | Description |
| ------------------ | ------------------------- | ----------------------- |
| `id` | string (UUID) | Exposure identifier |
| `companyId` | string (UUID) | Company identifier |
| `fieldModelV1Data` | object | Custom field data |
| `policyIds` | string\[] | Associated policy IDs |
| `createdAt` | string (ISO 8601) \| null | Creation timestamp |
| `updatedAt` | string (ISO 8601) \| null | Last update timestamp |
| `createdBy` | string \| null | User ID of creator |
| `updatedBy` | string \| null | User ID of last updater |
### Event
Events represent claims and incidents.
| Field | Type | Description |
| ------------------ | ------------------------- | ----------------------- |
| `id` | string (UUID) | Event identifier |
| `companyId` | string (UUID) | Company identifier |
| `policyId` | string (UUID) \| null | Associated policy |
| `fieldModelV1Data` | object | Custom field data |
| `createdAt` | string (ISO 8601) \| null | Creation timestamp |
| `updatedAt` | string (ISO 8601) \| null | Last update timestamp |
| `createdBy` | string \| null | User ID of creator |
| `updatedBy` | string \| null | User ID of last updater |
### Quote
Quotes are top-level FMV1 entities with their own field definitions. On bind, a quote creates a new policy.
| Field | Type | Description |
| -------------- | ------------------------- | ------------------------------------ |
| `id` | string (UUID) | Quote identifier |
| `companyId` | string (UUID) | Company identifier |
| `submissionId` | string (UUID) | Parent submission |
| `policyId` | string (UUID) \| null | Associated policy (set after bind) |
| `data` | object | Quote-level custom field data |
| `exposures` | object\[] | Array of exposure field data objects |
| `createdAt` | string (ISO 8601) | Creation timestamp |
| `updatedAt` | string (ISO 8601) \| null | Last update timestamp |
| `createdBy` | string \| null | User ID of creator |
Quotes use `data` and `exposures` rather than `fieldModelV1Data` because they contain data for two entity types in a single response. Quote-specific fields (quoteStatus, quoteType, quoteNumber, quoteSubmissionId, quoteBindErrors) are system-managed and cannot be set via the API.
**Quote configuration** returns schemas for both entity types:
```json theme={null}
{
"quote": { "$schema": "...", "type": "object", "properties": { ... } },
"exposure": { "$schema": "...", "type": "object", "properties": { ... } }
}
```
The `quote` schema excludes calculated fields, policy-only fields, server-populated fields, and lifecycle fields. The `exposure` schema (singular) describes the shape of **each item** in the quote's `exposures` array (plural).
### Custom Object
Custom objects are configurable entity types with relationships to other objects.
| Field | Type | Description |
| --------------- | ------------------------- | ----------------------- |
| `id` | string (UUID) | Object identifier |
| `companyId` | string (UUID) | Company identifier |
| `type` | string | Object type name |
| `displayName` | string | Computed display name |
| `data` | object | Custom field data |
| `relationships` | object | Relationship mappings |
| `createdAt` | string (ISO 8601) \| null | Creation timestamp |
| `updatedAt` | string (ISO 8601) \| null | Last update timestamp |
| `createdBy` | string \| null | User ID of creator |
| `updatedBy` | string \| null | User ID of last updater |
**Custom object configuration** includes field schema and relationship definitions:
```json theme={null}
{
"data": { "$schema": "...", "type": "object", "properties": { ... } },
"relationships": [
{
"fieldRefId": "primaryBroker",
"label": "Primary Broker",
"targetType": "broker",
"cardinality": "many_to_one"
}
]
}
```
**Relationship cardinality values:** `one_to_one`, `one_to_many`, `many_to_one`, `many_to_many`
***
## Policy Model
Policies use a **transaction-based, temporally-versioned** data model. Rather than directly editing policy fields, you submit transactions (new business, endorsement, cancellation, etc.) that produce immutable versions.
For a deep dive, see [Policy Concepts](/api-v1-reference/policies/concepts).
### Policy Version
Each transaction produces a new policy version containing one or more **segments** — date ranges where the policy state is identical.
| Field | Type | Description |
| ----------------------- | ----------------- | -------------------------------------- |
| `policyId` | string (UUID) | Policy identifier |
| `policyVersion` | integer | Version number (incrementing) |
| `transactionId` | string (UUID) | Transaction that produced this version |
| `startDate` | string (date) | Policy term start |
| `endDate` | string (date) | Policy term end |
| `createdAt` | string (ISO 8601) | Version creation timestamp |
| `fullTermPolicyBilling` | object \| null | Billing data for the full term |
| `fullTermPolicyInfo` | object \| null | Policy info for the full term |
| `segments` | PolicySegment\[] | Array of policy segments |
### Policy Segment
A segment is a date range within the policy term where the policy state is constant. Segments are **derived from final state** — they are not one-per-transaction.
| Field | Type | Description |
| ------------------ | ------------- | ------------------------------------- |
| `startDate` | string (date) | Segment start date |
| `endDate` | string (date) | Segment end date |
| `fieldModelV1Data` | object | Policy field data for this date range |
### Policy Transaction
Transactions are the immutable record of changes to a policy.
| Field | Type | Description |
| ---------------------- | ------------------- | ---------------------------------- |
| `id` | string (UUID) | Transaction identifier |
| `policyId` | string (UUID) | Policy identifier |
| `policyVersion` | integer | Version this transaction produced |
| `action` | string | Transaction type (see below) |
| `effectiveDate` | string (date) | When this change takes effect |
| `transactionTimestamp` | string (ISO 8601) | When this transaction was recorded |
| `createdAt` | string (ISO 8601) | Creation timestamp |
| `createdBy` | string \| null | User ID of creator |
| `deltas` | TransactionDelta\[] | Field-level changes (optional) |
**Transaction action values:** `NEW_BUSINESS`, `ENDORSE`, `CANCEL`, `REINSTATE`, `RENEW`
### Transaction Delta
Deltas describe the field-level changes a transaction made within a date range.
| Field | Type | Description |
| --------------- | ------------------------- | ------------------------------------- |
| `id` | string (UUID) | Delta identifier |
| `transactionId` | string (UUID) | Parent transaction |
| `startDate` | string (date) | Date range start |
| `endDate` | string (date) | Date range end |
| `path` | string | JSON pointer to the changed field |
| `action` | string | `Add`, `Remove`, or `Overwrite` |
| `value` | string, number, or object | New value (for `Add` and `Overwrite`) |
### Policy List Item
List endpoints return a summary with optional segment detail:
```json theme={null}
{
"summary": {
"id": "...",
"policyId": "...",
"companyId": "...",
"createdAt": "2026-01-15T10:30:00.000Z",
"policyVersion": 3,
"versionCreatedAt": "2026-03-01T14:00:00.000Z",
"fullTermPolicyBilling": null,
"fullTermPolicyInfo": { ... },
"matchedSegments": [
{ "startDate": "2026-01-15", "endDate": "2026-07-15" }
]
},
"segments": []
}
```
### Earned Premium
Per-policy earned premium calculations, available at different detail levels.
| Field | Type | Description |
| -------------------- | ------------------ | -------------------------------------- |
| `policyId` | string (UUID) | Policy identifier |
| `policyNumber` | string | Human-readable policy number |
| `earnedPremiumTotal` | number | Total earned premium for the period |
| `transactionTotals` | array | Per-transaction contribution breakdown |
| `days` | array \| undefined | Per-day breakdown (when requested) |
**Detail levels** (set via `detail` query parameter):
| Value | Description |
| --------------------- | ---------------------------------------------------- |
| `transactions` | Per-transaction totals only (default) |
| `days` | Adds daily earned premium totals |
| `daysAndTransactions` | Adds daily totals with per-transaction contributions |
### Bordereau Row
Bordereau export provides a flat row per policy transaction for reporting.
| Field | Type | Description |
| ---------------------- | ----------------- | ------------------------------------- |
| `policyNumber` | string \| null | Policy number |
| `primaryInsuredName` | string \| null | Primary insured |
| `transactionAction` | string | Transaction type |
| `policyVersion` | integer | Version number |
| `effectiveDate` | string (date) | Transaction effective date |
| `transactionTimestamp` | string (ISO 8601) | When recorded |
| `policyStartDate` | string (date) | Term start |
| `policyEndDate` | string (date) | Term end |
| `createdAt` | string (ISO 8601) | Creation timestamp |
| `createdBy` | string \| null | Creator |
| `policyPremium` | number \| null | Total premium at this version |
| `policyPremiumChange` | number \| null | Premium change from prior version |
| `additionalColumns` | object | Company-configured additional columns |
***
## Entity Relationships
```
Submission ──has many──> Quotes
Quote ──binds to──> Policy (one-to-one)
Policy ──has many──> Transactions ──produces──> Versions ──contains──> Segments
Exposure ──standalone entity──
Quote / Policy ──embeds──> Exposure data (snapshot, can diverge)
Event ──optionally linked──> Policy (via policyId)
Custom Object ──relationships──> Custom Object (configurable cardinality)
```
| Relationship | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Quote → Policy | Binding a quote creates a policy and sets `policyId` on the quote |
| Policy → Transactions | Transactions are the write path; each produces a new version |
| Policy → Versions → Segments | Versions contain segments representing the policy state over time |
| Quote / Policy → Exposure | Quotes and policies **embed** exposure data. They store a reference back to the standalone exposure object, but the embedded exposure data can evolve independently — e.g., an endorsement may change exposure fields on the policy without modifying the standalone exposure record |
| Event → Policy | Events may reference a policy via `policyId` |
| Custom Object → Custom Object | Configurable relationships with defined cardinality |