Data Models - AI Insurance

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:

{
  "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:

{
  "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:

{
  "exposureType": "commercial_property"
}

Multi-select:

{
  "coverageLines": ["general_liability", "property", "auto"]
}

The configuration schema uses oneOf to enumerate valid options:

{
  "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:

{
  "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 each entity’s overview page (Exposures, Events, Quotes, Submissions, Persons, Organizations) for its framework-required fields and example payloads.

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

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
`fullTermPolicyInfo`	object \| null	Endorsable full-term policy info (term dates, renewal pointer, primary insured) — hoisted read-once
`fullTermPolicyBillingInfo`	object \| null	Derived full-term billing aggregates — 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
`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:

{
  "summary": {
    "id": "...",
    "policyId": "...",
    "companyId": "...",
    "createdAt": "2026-01-15T10:30:00.000Z",
    "policyVersion": 3,
    "versionCreatedAt": "2026-03-01T14:00:00.000Z",
    "fullTermPolicyInfo": { ... },
    "fullTermPolicyBillingInfo": null,
    "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 ──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

​Common Conventions

​IDs

​Timestamps

​Dates

​Nullable Fields

​Pagination

​Unified entity list endpoints

​Notes, tasks, and files

​fieldModelV1Data

​Field Value Types

​Date Fields

​Option Set Fields

​Configuration Schema

​Schema Format Values

​Entities

​Entity envelope

​Directory entities (Persons & Organizations) and custom objects

​Policy Model

​Policy Version

​Policy Segment

​Policy Transaction

​Transaction Delta

​Policy List Item

​Earned Premium

​Bordereau Row

​Entity Relationships

Common Conventions

IDs

Timestamps

Dates

Nullable Fields

Pagination

Unified entity list endpoints

Notes, tasks, and files

fieldModelV1Data

Field Value Types

Date Fields

Option Set Fields

Configuration Schema

Schema Format Values

Entities

Entity envelope

Directory entities (Persons & Organizations) and custom objects

Policy Model

Policy Version

Policy Segment

Policy Transaction

Transaction Delta

Policy List Item

Earned Premium

Bordereau Row

Entity Relationships