Skip to main content
POST

Authorizations

Authorization
string
header
required

API key authentication. Send your raw API key as the Authorization header value with NO scheme prefix — Authorization: YOUR-API-KEY. Do NOT prefix it with Bearer or ApiKey, and do not use an X-API-Key header; those are not accepted.

Headers

Idempotency-Key
string

A unique key of 1 to 255 printable ASCII characters for retrying this write. Within 30 days of the successful attempt's admission, reuse with the same request returns the original transaction; retries do not extend that window. After 30 days the same key runs as a new write, even if the request differs.

Required string length: 1 - 255

Path Parameters

companyId
string<uuid>
required

Company identifier

Body

application/json
data
object
required

The policy-level fields, at the top level of this object. Must include policyStartDate and policyEndDate. May also include fullTermPricingInfo, fullTermBillingInfo, fullTermPolicyRatingResult and any custom fields defined in your field configuration — including embedded exposure fields (the default configuration models a primaryInsured object + an additionalExposures list, but the platform imposes no structural exposure shape).

Custom fields — including the values of any embedded exposure fields — are validated against your company's field configuration. Unknown fields are rejected, required fields must be present, and values must match their configured types (including option set membership). Embedded exposure values are validated per-field against that exposure's own configuration.

Before 2026-08-05 these same fields were sent one level deeper, inside fieldModelV1Data.policy. Send data.policyNumber where you sent fieldModelV1Data.policy.policyNumber.

transactionTimestamp
string<date-time>

When the business decision was made. Defaults to the current time if omitted. Set explicitly for imports (e.g., aligning to a bordereau booking date).

displayAuthor
string

Optional user-visible author label (trimmed; must be non-empty). When set, the transaction is displayed as filed by this label (e.g. "Data Import") instead of the acting user; audit attribution (createdBy) stays server-set.

Maximum string length: 255
invoicePlan
object

A fully explicit, detached policy-invoice batch. Existing invoices not named in voidInvoices are kept. The complete kept-plus-created set must conserve each line item of the policy's stated billing. A line item a kept invoice carries but billing omits conserves at 0: a create may credit it on the same line with a negative amount. A plan never names a move between layers of the pricing stack: a policy transaction or bind by value names its own beside the plan in pricingStackLayerChange, and a quote's plan binds at the quote's intended layer. Invoice plans explains each field, the rule and every refusal.

Response

Policy created successfully

Response returned by policy transaction endpoints. Contains the policy version produced by the transaction, including all derived segments.

policyId
string<uuid>
required

Policy identifier

policyVersion
integer
required

Sequential version number produced by this transaction

transactionId
string<uuid>
required

Identifier of the transaction that produced this version

startDate
string<date>
required

Policy term start date (ISO 8601)

endDate
string<date>
required

Policy term end date (ISO 8601)

createdAt
string<date-time>
required

When the transaction was created (ISO 8601)

primaryInsuredName
string | null
required

Plain-text primary-insured name, read from the policy's own primaryInsuredName field — the source of truth for the primary insured. Reported as of the END of the term, so a policy whose insured changed mid-term returns the later name; segments[] carries the per-segment history. Null only when the version carries no policy data.

primaryInsuredId
string | null
required

Id of the entity behind primaryInsuredName. Null when the policy's configuration does not populate it.

policyNumber
string | null
required

The policy number, read from the policy's own policyNumber field — the source of truth, invariant across the whole term. Null only when the version carries no policy data.

policyStartDate
object | null
required

Policy term start date as the structured date object, read from the policy's own policyStartDate field — the source of truth, invariant across the whole term. This is not startDate above: that is the ISO span this version covers, which a cancellation makes shorter than the term. Null only when the version carries no policy data.

policyEndDate
object | null
required

Policy term end date as the structured date object, read from the policy's own policyEndDate field — the source of truth, invariant across the whole term. This is not endDate above: that is the ISO span this version covers. Null only when the version carries no policy data.

fullTermPricingInfo
object | null
required

The policy's full-term pricing contract, hoisted as a read-once convenience (also duplicated in every segment): pricingComponents plus the four server-computed, read-only rollups — premium, taxes and fees (each the sum of the components whose classification reports into it) and total (premium + taxes + fees). All four are always present. The retired brokerCommission / programCommission rollups are no longer computed; a version stored before their retirement may still return the two keys until the per-tenant data sweeps.

Each newly written component carries {label, value, classification, qualifier, earningSchedule} — <classification, qualifier> is its identity, and label is cosmetic. The legacy vocabulary is retired: a component stored before the retirement may still echo the group / kind / earningBasis keys until the per-tenant data sweeps remove them — treat those as historical output, never as identity, and do not rely on their presence.

fullTermBillingInfo
object | null
required

The policy's Billing Aggregate for the term, hoisted as a read-once convenience (also duplicated in every segment). Null when the policy states no billing obligations.

fullTermPolicyRatingResult
object | null
required

Derived canonical policy-level rating result for the full term, hoisted as a read-once convenience (also duplicated in every segment). Element-level rating output (crossSegmentRatingOutputs) stays inline at its host and is not hoisted.

segments
object[]
required

Derived segments for this policy version. Each segment represents a maximal contiguous date range where policy state is identical. Adjacent segments with identical data are automatically merged.