Policy Transactions
PolicyCoverageChangesRequest
objectRequest body for a bundle of in-force coverage/rider changes
(POST /bpm/v1/policies/{planCode}/{policyNumber}/policyCoverageChanges
and policy API alias).
caseIdstringrequired
Unique identifier of the in-force case associated with this policy update, used to correlate the request with the case management system
Example:CA1234567890
correlationIdstring(uuid)required
The unique ID to track this transaction request across all systems
Example:381ee1cc-7f34-47b1-a007-948d26b68a0f
effectiveDatestring(date)required
Transaction-level effective date, used as the default effective date for any policyUpdateRequest item that does not specify its own effectiveDate
Example:2026-07-15
externalIdentifiersobject
Show Child Parameters
policyUpdateRequest
One Ofarray[object]required
A single policy-update request item. The shape of the remaining properties depends on requestType.
>= 1 items
DeathBenefitOptionChangeobject
Death Benefit Option change request item
Show Child Parameters
paymentobject
Recurring premium/billing arrangement for this transaction, required only if at least one policyUpdateRequest item impacts premium (BASECOVERAGEUPDATE, RIDERADD, RIDERUPDATE).
Show Child Parameters
oneTimePaymentobject
One-time payment accompanying this transaction, present only when the transaction includes a one-time payment
Show Child Parameters
illustrationsobject
Show Child Parameters
partiesarray[object]
Parties referenced by this transaction’s policyUpdateRequest, payment, and oneTimePayment items
Show Child Parameters
underwritingobject
Underwriting decision evaluated for this policy update, present when an underwriting case was evaluated
Show Child Parameters
identifiersarray[object]
Business identifier associated with the case, using Zinnia’s existing {identifier, value} convention
Show Child Parameters
Example
PolicyCoverageChangesExternalIdentifiers
objectexternalTransactionIdstring
Transaction identifier assigned by the external/source system submitting the request
Example:test
referenceNumberstring
Additional reference number supplied by the external system for tracking purposes
Example:uniquetest1233
Example
PolicyCoverageChangesRequestItem
objectA single policy-update request item. The shape of the remaining properties depends on requestType.
One OfrequestTypestringrequired
Discriminator identifying this item as a Death Benefit Option change request
Allowed values:DEATHBENEFITOPTIONCHANGE
Example:DEATHBENEFITOPTIONCHANGE
coverageIdstring
Coverage ID received from the policy admin system
Example:Base_Coverage
coverageTypestring
Type of the coverage
Allowed values:BASETERMSUPPLEMENTAL
Example:BASE
deathBenefitOptionstringrequired
New death benefit option elected for the coverage
Allowed values:LEVELINCREASING
Example:LEVEL
deathBenefitComplianceTeststring
IRC compliance test the policy is administered under after the change
Allowed values:GPTCVAT
Example:GPT
Example
DeathBenefitOptionChange
objectDeath Benefit Option change request item
requestTypestringrequired
Discriminator identifying this item as a Death Benefit Option change request
Allowed values:DEATHBENEFITOPTIONCHANGE
Example:DEATHBENEFITOPTIONCHANGE
coverageIdstring
Coverage ID received from the policy admin system
Example:Base_Coverage
coverageTypestring
Type of the coverage
Allowed values:BASETERMSUPPLEMENTAL
Example:BASE
deathBenefitOptionstringrequired
New death benefit option elected for the coverage
Allowed values:LEVELINCREASING
Example:LEVEL
deathBenefitComplianceTeststring
IRC compliance test the policy is administered under after the change
Allowed values:GPTCVAT
Example:GPT
Example
BASECOVERAGEUPDATE
objectBase coverage face-amount increase request item
requestTypestringrequired
Discriminator identifying this item as a base coverage face-amount increase
Allowed values:BASECOVERAGEUPDATE
Example:BASECOVERAGEUPDATE
coverageIdstringrequired
Identifier of the coverage whose face amount is being increased
Example:Base_Coverage
coverageTypestringrequired
Type of the coverage
Allowed values:BASETERMSUPPLEMENTAL
Example:BASE
effectiveDatestring(date)
Effective date of the face increase; defaults to the transaction-level effectiveDate when omitted
Example:2026-07-15
faceAmountnumber(double)required
New total face amount for the coverage after the increase
Example:250000
tableRatingsobject
Substandard rating applied as a result of the change, if any
Show Child Parameters
Example