> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.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
Timestamp conventions differ between the **unified entity endpoints** and the **policy / task / file endpoints**:
* **Unified entity endpoints** (exposure, event, quote, submission, person, organization) return `createdAt` / `updatedAt` as **epoch-second integers** inside the entity envelope:
```
1736937000
```
* **Policy versions/transactions, tasks, files, and reporting** return timestamps such as `transactionTimestamp`, `createdAt`, and `deadline` as **ISO 8601** strings in UTC:
```
"2026-04-14T10:30:45.123Z"
```
Each entity's overview page documents its exact response shape.
### 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
Pagination differs between the **unified entity list endpoints** and the **notes / tasks / files list endpoints**.
### Unified entity list endpoints
The entity list endpoints (exposure, event, quote, submission, person, organization) return:
```json theme={null}
{
"items": [],
"hasMore": false,
"totalCount": 0
}
```
| Field | Type | Description |
| ------------ | ------- | --------------------------------------- |
| `items` | array | Entity envelopes for the current page |
| `hasMore` | boolean | Whether more pages exist after this one |
| `totalCount` | integer | Total matching records across all pages |
**Query parameters:**
| Parameter | Type | Default | Description |
| --------------- | --------------- | ----------- | ----------------------------------------- |
| `filterText` | string | — | Free-text search (entity-specific fields) |
| `sortBy` | string | `createdAt` | Field to sort by (any configured field) |
| `sortDirection` | `asc` \| `desc` | `desc` | Sort direction |
| `pageNumber` | integer | `0` | **Zero**-based page index |
| `pageSize` | integer | `51` | Items per page |
### Notes, tasks, and files
The notes, tasks, and company-files list endpoints use **1-based** `page` / `pageSize` query parameters (`page=1` is the first page). See each endpoint's reference for its exact response shape.
***
## 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, wrapped under a top-level `fields` key:
```json theme={null}
{
"fields": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"fieldReferenceId": {
"type": "string",
"title": "fieldReferenceId",
"format": "date"
}
},
"required": ["fieldReferenceId"]
}
}
```
For entities that embed exposures (Quote), the embedded exposure schema is **nested under the corresponding join field** (e.g. `exposures`) within the same `fields` schema, not returned as a separate top-level key. Calculated values, server-populated fields, and lifecycle fields are excluded.
### 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
### Entity envelope
The unified entity endpoints (exposure, event, quote, submission, person, organization) all return the **same generic envelope**. All entity-specific field values live inside `fieldModelV1Data`, keyed by field `referenceId` — there is no top-level `companyId`, `policyId`, or `submissionId`.
| Field | Type | Description |
| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string (UUID) | Entity identifier |
| `fieldModelV1Data` | object | Field values keyed by `referenceId`, including calculated/auto-set values (e.g. `submissionNumber`, `quoteStatus`) and join field IDs |
| `createdAt` | integer (epoch seconds) | Creation time |
| `createdBy` | string \| null | User ID of the creator, or null |
| `updatedAt` | integer (epoch seconds) | Last update time (equals `createdAt` if never updated) |
| `updatedBy` | string \| null | User ID of the last updater, or null |
| `createdByName` | string \| null | Display name resolved from `createdBy` |
| `updatedByName` | string \| null | Display name resolved from `updatedBy` |
See the [Entities overview](/api-reference/entities/overview) for the parametric CRUD surface shared by every entity type (exposures, events, quotes, submissions, persons, organizations), and discover each type's framework-required fields via its [configuration endpoint](/api-reference/entities/get-entity-configuration).
Cross-entity links are expressed as **Join fields inside `fieldModelV1Data`** (for example `quoteSubmission` on a quote, or `eventPolicy` on an event), not as separate top-level keys. Calculated and lifecycle fields (e.g. `quoteStatus`, `quoteNumber`, `submissionNumber`) are resolver-populated and cannot be set via the API.
The `/configuration` response shape is documented under [Configuration Schema](#configuration-schema) above.
### Directory entities (Persons & Organizations) and custom objects
Persons and Organizations are built-in **Directory** entities backed by the custom-object model; both use the entity envelope above and the `company.fmv1_custom_object:*` permission family. Configurable relationships between objects use these cardinality values:
**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-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 |
| `primaryInsuredName` | string \| null | Primary insured's display name, read from the policy root |
| `primaryInsuredId` | string \| null | Id of the entity behind `primaryInsuredName` |
| `policyNumber` | string \| null | The policy number, read from the policy root. Invariant across the term |
| `policyStartDate` | [Date](/api-reference/object-primitives/overview#date) \| null | Policy term start, read from the policy root. The structured date object, not the `startDate` ISO span above |
| `policyEndDate` | [Date](/api-reference/object-primitives/overview#date) \| null | Policy term end, read from the policy root |
| `fullTermPricingInfo` | object \| null | The full-term pricing contract — `pricingComponents` plus the five server-computed, read-only rollups (`premium`, `taxes`, `fees`, `brokerCommission`, `programCommission`) — hoisted read-once |
| `fullTermPolicyRatingResult` | object \| null | Derived canonical policy-level rating result — hoisted read-once |
| `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 |
| `data` | 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",
"policyNumber": "POL-2026-000123",
"policyStartDate": { "year": 2026, "month": 1, "day": 15, "timezone": "America/New_York" },
"policyEndDate": { "year": 2027, "month": 1, "day": 15, "timezone": "America/New_York" },
"fullTermPricingInfo": null,
"matchedSegments": [
{ "startDate": "2026-01-15", "endDate": "2026-07-15" }
]
},
"segments": []
}
```
### 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 |
| `fieldColumns` | object | Requested field columns (`{"kind":"field"}` entries of `columns`), keyed by header |
***
## Entity Relationships
```
Submission ──has many──> Quotes
Quote ──seeds──> Policy (created via transaction)
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 | A quote's data can seed a policy created via a `new-business` transaction; `policyId` links the two |
| 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 |