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

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:

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

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

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

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

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

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:

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

​Common Conventions

​IDs

​Timestamps

​Dates

​Nullable Fields

​Pagination

​fieldModelV1Data

​Field Value Types

​Date Fields

​Option Set Fields

​Configuration Schema

​Schema Format Values

​Entities

​Exposure

​Event

​Quote

​Custom Object

​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

fieldModelV1Data

Field Value Types

Date Fields

Option Set Fields

Configuration Schema

Schema Format Values

Entities

Exposure

Event

Quote

Custom Object

Policy Model

Policy Version

Policy Segment

Policy Transaction

Transaction Delta

Policy List Item

Earned Premium

Bordereau Row

Entity Relationships