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

Endpoint-level date parameters such as startDate, endDate, and effectiveDate use ISO 8601 date strings ("2026-01-15"). Values in fields typed Date use the canonical object described below, including policy policyStartDate and policyEndDate fields.

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`	`{ "date": "2026-01-15", "timezone": "America/New_York" }`
Single-select option set	`string`	`"commercial"`
Multi-select option set	`array` of `string`	`["general_liability", "property"]`

Date Fields

Date fields are one canonical object — a calendar day pinned to an IANA time zone:

{
  "policyEffectiveDate": {
    "date": "2026-01-15",
    "timezone": "America/New_York"
  }
}

Property	Type	Description
`date`	string	The calendar day as `YYYY-MM-DD` (zero-padded); must name a real calendar day
`timezone`	string	IANA time zone identifier. Optional on a write (defaults to `America/New_York`); always present in a response

Endpoint-level date parameters (such as a transaction’s effectiveDate, or a cancellation’s cancellationDate) are plain ISO 8601 date strings ("2026-01-15"), not the object. The object is the shape of every field typed Date inside field data — including the policy term dates policyStartDate / policyEndDate.

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": "object",
        "title": "fieldReferenceId",
        "properties": {
          "date": { "type": "string", "format": "date" },
          "timezone": {
            "type": "string",
            "enum": [
              "UTC",
              "Etc/UTC",
              "America/Adak",
              "America/Anchorage",
              "America/Boise",
              "America/Chicago",
              "America/Denver",
              "America/Detroit",
              "America/Indiana/Indianapolis",
              "America/Indiana/Knox",
              "America/Indiana/Marengo",
              "America/Indiana/Petersburg",
              "America/Indiana/Tell_City",
              "America/Indiana/Vevay",
              "America/Indiana/Vincennes",
              "America/Indiana/Winamac",
              "America/Juneau",
              "America/Kentucky/Louisville",
              "America/Kentucky/Monticello",
              "America/Los_Angeles",
              "America/Menominee",
              "America/Metlakatla",
              "America/New_York",
              "America/Nome",
              "America/North_Dakota/Beulah",
              "America/North_Dakota/Center",
              "America/North_Dakota/New_Salem",
              "America/Phoenix",
              "America/Sitka",
              "America/Yakutat",
              "Pacific/Honolulu"
            ]
          }
        },
        "required": ["date", "timezone"]
      }
    },
    "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 Type Shapes

The configuration response publishes the actual JSON shape of each field. Text, Phone, URL, and Email fields are strings; Number fields are numbers; Boolean fields are booleans; and Percentage fields are scaled integers. Date, Address, AddressV2, and custom-object fields publish their nested object properties. Option-set fields are strings with oneOf entries and an x-optionSetName; list cardinality wraps the field shape in an array. Join fields use a format such as entity:exposure and contain an entity ID (or an array of IDs for a list join). For a Date field, the nested date string carries format: date; the Date field itself remains the canonical object. The response schema requires both date and timezone because those are always present in stored and returned values. On API writes, timezone may still be omitted and defaults to America/New_York.

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 for the parametric CRUD surface shared by every entity type (exposures, events, quotes, submissions, persons, organizations), and discover each type’s caller-required fields via its configuration endpoint — the keys you must send on a create, because nothing in the pipeline produces them.

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
`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 \| null	Policy term start, read from the policy root. The structured date object, not the `startDate` ISO span above
`policyEndDate`	Date \| null	Policy term end, read from the policy root
`fullTermPricingInfo`	Pricing Contract \| null	The full-term pricing contract — `pricingComponents` plus the four server-computed, read-only rollups — hoisted read-once
`fullTermBillingInfo`	Billing Aggregate \| null	The full-term billing obligations, per line item — hoisted read-once
`fullTermPolicyRatingResult`	object \| null	Derived canonical policy-level rating result — hoisted read-once
`segments`	PolicySegment[]	Array of policy segments

Pricing Contract

fullTermPricingInfo: null means no policy pricing and is supported on both policies and quotes. A present fullTermPricingInfo object is the policy’s price for the whole term. It is invariant across every segment, and it appears both hoisted at the response root and inside each segment’s data.

Field	Type	Description
`pricingComponents`	PricingComponent[]	Required array of itemized charges; may be empty
`premium`	number	Read-only. Sum of the components whose `classification` reports into the premium rollup
`taxes`	number	Read-only. Sum of the components whose `classification` reports into the taxes rollup
`fees`	number	Read-only. Sum of the components whose `classification` reports into the fees rollup
`total`	number	Read-only. `premium + taxes + fees` — every classification reports into exactly one of the three, so `total` accounts for every component

A present object always contains the component array and all four numeric rollups. An empty array produces zero for every rollup, which is distinct from outer null. Legacy API input with missing or null pricingComponents inside a present object is normalized to [] before stamping; reads return the required array. Lifecycle request omission retains each operation’s existing inherit/derive semantics and does not clear pricing. All four rollups are computed by the platform on every write and are always present on a non-null pricing response; a value you send is ignored and recomputed. Each registry entry names the rollup its classification reports into, which is how a component finds its rollup. Retired rollups. The brokerCommission and programCommission rollups are retired: commission is money owed by the carrier, not part of the policy’s price, so it belongs to the Billing Aggregate, not the pricing contract. The platform no longer computes them, and they were never writable. A policy version stored before the retirement may still return the two keys until the per-tenant data sweeps — treat them as historical output and do not rely on their presence.

Pricing Component

Every component you submit must carry a classification naming a live entry in your company’s classification registry — unconditionally, for every company. A component without one is rejected with a 400. The retired legacy fields (group / kind / earningBasis) are ignored and discarded on input: never validated, never stored on a newly written component. A stored component that still echoes them can be posted back unchanged (echo tolerance). See Pricing Component Identity for the defaults and the refusals.

Field	Type	Description
`label`	string	Display text. Always required. Cosmetic — identity lives in `<classification, qualifier>`
`value`	number	The charge amount in USD, a plain number. Always required
`classification`	string	A key naming a live entry in the company’s classification registry — the stable identity half. Required on every component, for every company
`qualifier`	string \| null	A structured qualifier such as a taxing jurisdiction. Defaults to `""`
`earningSchedule`	`pro-rata` \| `immediate` \| null	How the charge earns. Omitted means `pro-rata`
`group`	string	Retired. Ignored and discarded on input; still echoed on components stored before the retirement, until the per-tenant data sweeps
`kind`	string	Retired. Ignored and discarded on input; still echoed on components stored before the retirement, until the per-tenant data sweeps
`earningBasis`	string \| null	Retired — succeeded by `earningSchedule`. Ignored and discarded on input; still echoed on components stored before the retirement, until the per-tenant data sweeps

A component’s identity is the pair <classification, qualifier>, unique within one contract.

Billing Aggregate

fullTermBillingInfo is the policy’s term-level billing channel: what is owed, per line item, free of invoices. Like the pricing contract it is invariant across segments and hoisted onto responses, and it carries no classification and no rollup. You author it, except on a cancel or reinstate, where the platform derives it when you omit it.

Field	Type	Description
`lines`	BillingLine[] \| null	The term’s billing lines. Null when the policy states no obligations

Billing Line

Field	Type	Description
`invoiceType`	string	The kind of invoice the obligation belongs to, e.g. `"Policy Invoice"`. Required, non-empty
`lineItem`	string	The line item within that invoice type, e.g. `"Premium Installment"`. Required, non-empty
`direction`	`receivable` \| `payable`	`receivable` is owed to us; `payable` is owed by us (commission). Required
`amount`	number	A plain, signed, finite USD amount — a price refund is a negative receivable. Required

Identity is the pair <invoiceType, lineItem>, unique within one container. Structure is validated on every request; a stated aggregate must also satisfy the receivable checksum (the receivable amounts sum to fullTermPricingInfo.total) and per-line vocabulary and direction (each <invoiceType, lineItem> names a live invoice type and line item type, and direction matches how that line item is configured). See The Billing Aggregate.

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:

{
  "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": { "date": "2026-01-15", "timezone": "America/New_York" },
    "policyEndDate": { "date": "2027-01-15", "timezone": "America/New_York" },
    "fullTermPricingInfo": null,
    "fullTermBillingInfo": 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

​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 Type Shapes

​Entities

​Entity envelope

​Directory entities (Persons & Organizations) and custom objects

​Policy Model

​Policy Version

​Pricing Contract

​Pricing Component

​Billing Aggregate

​Billing Line

​Policy Segment

​Policy Transaction

​Transaction Delta

​Policy List Item

​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 Type Shapes

Entities

Entity envelope

Directory entities (Persons & Organizations) and custom objects

Policy Model

Policy Version

Pricing Contract

Pricing Component

Billing Aggregate

Billing Line

Policy Segment

Policy Transaction

Transaction Delta

Policy List Item

Bordereau Row

Entity Relationships