Endorse Policy Transaction
Applies an ENDORSE transaction to an existing policy. An endorsement carries one or more of four channels. The engine recomputes segments after applying every channel — adjacent segments with identical data are automatically merged — and the response includes the full resulting segment set.
Input channel:
deltas— changes to policy field data. Each carries its ownstartDate/endDatewithin the policy term, apath, anaction(Add / Remove / Overwrite), and avalue.
Amending the term. Shortening a term is a deltas write to the ROOT
policy.policyEndDate (or policy.policyStartDate) stating the whole term as
its window. There is no separate policy-info channel — the retired fullTermDeltas
container channel was removed once the root fields became the single writable
source.
Whole-term policy fields. Four ROOT paths hold values that are invariant across
the policy term — policy.policyNumber, policy.policyStartDate,
policy.policyEndDate and policy.previousPolicy. A delta on deltas that touches
one of them (at any depth, and including an ancestor path such as a whole-policy
Overwrite) must state the whole term as its window (startDate = the policy start,
endDate = the policy end) or the write is rejected.
A term bound may not move outward, through either input channel and at any path
depth: moving policyEndDate later or policyStartDate earlier is rejected
(TermLengtheningNotSupported), because no endorsement path can create the extra days.
Derived channels (additive on either input channel):
fullTermPricingInfo— whole-object overwrite of the policy-root pricing contract. SupplypricingComponents(each{label, group, kind, value[, earningBasis]}); the five rollups (premium,taxes,fees,brokerCommission,programCommission) are computed by the platform from the components — any caller-supplied rollup value is ignored and recomputed.fullTermPolicyRatingResult— whole-object overwrite of the policy-root canonical rating result (the twin offullTermPricingInfo).crossSegmentRatingOutputs— element-level rating output,[{ path, value }]. Eachpathterminates at acrossSegmentRatingOutputscontainer on a list element (or the policy);valueis the whole rating-output object for that host. There is no action (always an Overwrite) and no dates — the server derives each write’s range from the host’s presence across segments, so it applies cleanly to part-term hosts.
At least one channel is required.
Path syntax — predicate addressing. Index into a list by a predicate on any field:
policy.exposures[id = '<uuid>'].bedCount,
policy.coverages[coverageType = 'GL'].limits[name = 'occurrence']. The predicate must
resolve to exactly one element wherever it is applied (throws on zero or multiple
matches) — this uniqueness rule is the cross-segment identity guarantee.
Policy invoices. Optionally send invoicePlan, a fully explicit
keep/void/create plan. Nothing is defaulted or inferred. Once active
invoices exist, a pricing restatement must carry a conserving plan for the
new target; the version and invoices commit atomically.
Required permission: policy:update
Authorizations
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.
Path Parameters
Company identifier
Policy identifier
Body
The effective date of the endorsement in ISO 8601 format. It must fall within the policy term.
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).
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.
255Policy-data deltas. Each delta specifies a date range (startDate /
endDate) within the policy term, a predicate path, an action
(Add / Remove / Overwrite), and the new value. Paths must not contain any
reserved full-term container (fullTermPricingInfo,
fullTermPolicyRatingResult, crossSegmentRatingOutputs) — those have
their own channel. A delta on one of the four whole-term ROOT paths
(policy.policyNumber, policy.policyStartDate, policy.policyEndDate,
policy.previousPolicy) must span the whole term.
Optional whole-object overwrite of the policy-root full-term pricing
contract. Supply pricingComponents (each {label, group, kind, value[, earningBasis]}; kind one of Premium, Taxes, Fees,
BrokerCommission, ProgramCommission, Other; value a plain number;
earningBasis optional — omitted means pro-rata). The five rollups
(premium, taxes, fees, brokerCommission, programCommission)
are computed by the platform from the components; caller-supplied rollup
values are ignored and recomputed. Additive on either input channel.
Optional whole-object overwrite of the policy-root canonical rating result.
The twin of fullTermPricingInfo; additive on either input channel.
Optional element-level rating output. Each entry overwrites the
crossSegmentRatingOutputs container at its host; the server derives the write
range from the host's presence across segments (write where the host-selector
resolves to exactly one element, skip where zero, throw on many or if it never
resolves). Additive; ENDORSE only.
A fully explicit, detached policy-invoice batch. Existing invoices not named in voidInvoices are kept. The complete kept-plus-created set must conserve every bound component of the policy's current pricing contract.
Response
Endorsement applied successfully
Response returned by policy transaction endpoints. Contains the policy version produced by the transaction, including all derived segments.
Policy identifier
Sequential version number produced by this transaction
Identifier of the transaction that produced this version
Policy term start date (ISO 8601)
Policy term end date (ISO 8601)
When the transaction was created (ISO 8601)
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.
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.
Id of the entity behind primaryInsuredName. Null when the policy's
configuration does not populate it.
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.
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.
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.
The policy's full-term pricing contract, hoisted as a read-once convenience
(also duplicated in every segment): pricingComponents (each
{label, group, kind, value[, earningBasis]}) plus the five server-computed,
read-only rollups (premium, taxes, fees, brokerCommission,
programCommission — each the sum of its kind's components).
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.