Policy Transactions
Fullsurrender Validation Endpoint
post
Path Parameters
planCodestringrequired
policyNumberstringrequired
Body
application/json
Body
application/json
NewLoanRequest
correlationIdstring
The unique ID to track transaction request across all systems
Example:657b717b7dcf554abf9ef067
effectiveDatestring(date)required
Date (with pattern “yyyy-mm-dd”) when the transaction was originally scheduled or expected to happen, can be a non-business day
reverseInitiatorboolean
Property to isolate source transaction(s) that initiated the reversal
transactionAmountsobjectrequired
Show Child Parameters
fundAllocationobjectrequired
Show Child Parameters
taxWithholdingInstructionsarray[object]required
Show Child Parameters
partiesarray[object]required
Show Child Parameters
caseIdstring
Zinnia Live Case ID
Example:CA0000007389
Response
application/json
Response
application/json
Partial Withdrawal Success Response.yaml
TransactionResponse
statusstring
Allowed values:successfailure
errorarray[object]
Show Child Parameters
quoteResponseobject
post/policy/v1/transactions/{planCode}/{policyNumber}/newloan/validation
Authentication
Path Parameters
Body
{
"effectiveDate": "effectiveDate",
"transactionAmounts": {
"requestedAmount": 100,
"amountType": "AMOUNT",
"disbursementType": "GROSS",
"disbursementPaymentForm": "DTCC",
"loanType": "PREFERRED",
"loanInterestType": "FIXED"
},
"fundAllocation": {
"allocationOption": "PRORATA"
},
"taxWithholdingInstructions": [
{
"partyId": "Party_PI_1",
"taxWithholdingType": "FEDERAL",
"taxRateToUse": "NOWITHHOLDINGELECTED"
}
],
"parties": [
{
"partyId": "Party_PI_1",
"paymentForm": "DTCC",
"allocationPercentage": 100
}
]
}
application/json
Submit New Loan Request
post
Path Parameters
planCodestringrequired
policyNumberstringrequired
Body
application/json
Body
application/json
NewLoanRequest
correlationIdstring
The unique ID to track transaction request across all systems
Example:657b717b7dcf554abf9ef067
effectiveDatestring(date)required
Date (with pattern “yyyy-mm-dd”) when the transaction was originally scheduled or expected to happen, can be a non-business day
reverseInitiatorboolean
Property to isolate source transaction(s) that initiated the reversal
transactionAmountsobjectrequired
Show Child Parameters
fundAllocationobjectrequired
Show Child Parameters
taxWithholdingInstructionsarray[object]required
Show Child Parameters
partiesarray[object]required
Show Child Parameters
caseIdstring
Zinnia Live Case ID
Example:CA0000007389
Response
application/json
Response
application/json
Submit Transaction Successful
TransactionAcceptedResponse
correlationIdstring
Unique identifier which used by every system to trace the request
Example:3a2a3435-2089-4b81-9959-e0d569ccf4f0
caseIdstring
Zinnia Live Case ID
Example:CA0000369469
caseStatusstring
Zinnia Live Case Status
Example:IN_PROGRESS
pdfIdstring
Identifier for the generated or associated PDF document (e.g. OnBase document number). Returned on systematic program setup and update submit when available.
Example:DOC-10004567
post/policy/v1/transactions/{planCode}/{policyNumber}/newloan
Authentication
Path Parameters
Body
{
"effectiveDate": "effectiveDate",
"transactionAmounts": {
"requestedAmount": 100,
"amountType": "AMOUNT",
"disbursementType": "GROSS",
"disbursementPaymentForm": "DTCC",
"loanType": "PREFERRED",
"loanInterestType": "FIXED"
},
"fundAllocation": {
"allocationOption": "PRORATA"
},
"taxWithholdingInstructions": [
{
"partyId": "Party_PI_1",
"taxWithholdingType": "FEDERAL",
"taxRateToUse": "NOWITHHOLDINGELECTED"
}
],
"parties": [
{
"partyId": "Party_PI_1",
"paymentForm": "DTCC",
"allocationPercentage": 100
}
]
}
application/json
Submit Policy Coverage Changes
Submits a bundle of in-force coverage/rider changes (death benefit option change, face amount increase, risk-class reclassification, rider add, rider update/termination) for a single policy, along with the underwriting decision and any resulting premium/one-time payment that supports them.
post
Path Parameters
planCodestringrequired
policyNumberstringrequired
Body
application/json
Body
application/json
PolicyCoverageChangesRequest
Request 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
Response
application/json
Response
application/json
Submit Transaction Successful
TransactionAcceptedResponse
correlationIdstring
Unique identifier which used by every system to trace the request
Example:3a2a3435-2089-4b81-9959-e0d569ccf4f0
caseIdstring
Zinnia Live Case ID
Example:CA0000369469
caseStatusstring
Zinnia Live Case Status
Example:IN_PROGRESS
pdfIdstring
Identifier for the generated or associated PDF document (e.g. OnBase document number). Returned on systematic program setup and update submit when available.
Example:DOC-10004567
post/policy/v1/transactions/{planCode}/{policyNumber}/policycoveragechanges
Authentication
Path Parameters
Body
{
"caseId": "CA1234567890",
"correlationId": "381ee1cc-7f34-47b1-a007-948d26b68a0f",
"effectiveDate": "2026-07-15",
"externalIdentifiers": {
"externalTransactionId": "test",
"referenceNumber": "uniquetest1233"
},
"policyUpdateRequest": [
{
"requestType": "DEATHBENEFITOPTIONCHANGE",
"deathBenefitOption": "LEVEL",
"deathBenefitComplianceTest": "GPT",
"coverageId": "Base_Coverage",
"coverageType": "BASE"
},
{
"requestType": "BASECOVERAGEUPDATE",
"coverageId": "Base_Coverage",
"coverageType": "BASE",
"effectiveDate": "2026-07-15",
"faceAmount": 250000,
"tableRatings": {
"tableRating": "TABLEA",
"flatExtras": [
{
"type": "PERMANENT",
"amount": 250000,
"duration": 250000,
"durationType": "YEARS"
}
]
}
},
{
"requestType": "RECLASSIFICATION",
"coverageId": "Base_Coverage",
"effectiveDate": "2026-07-15",
"coverageType": "BASE",
"riskClass": "ULTRANONTOBACCO",
"tableRatings": {
"tableRating": "TABLEA",
"flatExtras": [
{
"type": "PERMANENT",
"amount": 250000,
"duration": 5,
"durationType": "YEARS"
}
]
}
},
{
"requestType": "RIDERADD",
"type": "Rider_ABRTRM",
"effectiveDate": "2026-07-15",
"faceAmount": 25000,
"premium": 15,
"status": "ACTIVE",
"optedForPolicy": "YES",
"tableRatings": {
"tableRating": "TABLEA",
"flatExtras": [
{
"type": "PERMANENT",
"amount": 250000,
"duration": 5,
"durationType": "YEARS"
}
]
},
"party": [
"5f8f2f5c-6c3b-4e3b-8f2f-5c6c3b4e3b8f"
]
},
{
"requestType": "RIDERUPDATE",
"type": "Rider_ABRTRM",
"effectiveDate": "2026-07-15",
"faceAmount": 25000,
"premium": 15,
"status": "ACTIVE",
"optedForPolicy": "YES",
"tableRatings": {
"tableRating": "TABLEA",
"flatExtras": [
{
"type": "PERMANENT",
"amount": 250000,
"duration": 5,
"durationType": "YEARS"
}
]
},
"party": [
"5f8f2f5c-6c3b-4e3b-8f2f-5c6c3b4e3b8f"
]
},
{
"requestType": "RIDERUPDATE",
"riderId": "Rider_ABRTRM_2",
"type": "Rider_ABRTRM",
"effectiveDate": "2026-07-15",
"status": "TERMINATE",
"reasonCode": "INSUREDREQUEST",
"party": [
"5f8f2f5c-6c3b-4e3b-8f2f-5c6c3b4e3b8f"
]
}
],
"payment": {
"referenceNumber": "5f2e0c1a-6b3d-4d3f-8b7f-3f7b6d5e4c3a",
"method": "ACH",
"arrangementType": "PAYMENT",
"frequency": "MONTHLY",
"amount": 250000,
"draftDate": "2023-01-01",
"paymentDate": "2023-01-01",
"externalTransactionId": "A12345",
"externalArrangementId": "B45678",
"party": [
"5f8f2f5c-6c3b-4e3b-8f2f-5c6c3b4e3b8f"
],
"bankInformation": {
"nameOnAccount": "abc",
"accountStatus": "ACTIVE",
"accountNumber": "1234567890",
"routingNumber": "123456789",
"accountType": "CHECKING",
"ibaNumber": "123456789",
"branchName": "XYZ Branch",
"address": {
"addressType": "RESIDENCE",
"addressLine1": "123 Main St",
"addressLine2": "Apt 4B",
"addressLine3": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"zipCode": "94105",
"zipCodeExt": "4465",
"country": "US"
}
}
},
"oneTimePayment": {
"requestedAmount": 25000,
"parties": [
{
"partyId": "Party_PI_1",
"paymentForm": "DTCC",
"bankId": "bank_1",
"partyRole": "PAYOR"
}
]
},
"illustrations": {
"source": "ZINNIA",
"illustrationId": "Q12345"
},
"parties": [
{
"partyId": "2ad51ecf-9923-437f-a6f0-70968e464cdb",
"partyRole": "INSURED",
"partyType": "INDIVIDUAL",
"personalInformation": {
"firstName": "John",
"middleName": "M",
"lastName": "Doe",
"suffix": "SR",
"prefix": "MR",
"dateOfBirth": "1990-01-01",
"gender": "MALE",
"birthSex": "MALE",
"birthCountry": "US",
"citizenCountry": "US"
},
"partyCommunication": "REGULARMAIL",
"identifiers": [
{
"type": "PASSPORT",
"value": "123456789",
"description": "Passport number",
"source": "State of California",
"issueDate": "2015-08-15",
"expirationDate": "2025-08-15",
"status": "ACTIVE",
"countryOfIssue": "US"
}
],
"address": {
"preferredAddressId": "2ad51ecf-9923-437f-a6f0-70968e464cdb",
"addresses": [
{
"id": "2ad51ecf-9923-437f-a6f0-70968e464cdb",
"addressType": "RESIDENCE",
"addressLine1": "123 Main St",
"addressLine2": "Apt 4B",
"addressLine3": "Apt 4B",
"city": "San Francisco",
"state": "CA",
"zipCode": "94105",
"zipCodeExt": "4465",
"country": "US"
}
]
},
"phoneNumber": {
"preferredPhoneId": "2ad51ecf-9923-437f-a6f0-70968e464cdb",
"phoneNumbers": [
{
"type": "MOBILE",
"countryCode": "9",
"areaCode": "973",
"dialNumber": "765789",
"extension": null,
"bestTime": null,
"timezone": null,
"id": "2ad51ecf-9923-437f-a6f0-70968e464cdb"
}
]
},
"email": {
"preferredEmailId": "2ad51ecf-9923-437f-a6f0-70968e464cdb",
"emails": [
{
"type": "PERSONAL",
"address": "user@example.com",
"id": "2ad51ecf-9923-437f-a6f0-70968e464cdb"
}
]
},
"signatures": [
{
"date": "2021-01-12",
"city": "Quincy",
"state": "CA"
}
]
}
],
"underwriting": {
"underwritingCaseId": "CA1234567890",
"decision": "APPROVED",
"status": "CLEAN_CASE",
"underwritingSourceName": "Source Details",
"underwritingRiskClass": "ULTRANONTOBACCO",
"decisionRiskClass": "ULTRANONTOBACCO",
"underwritingMethod": "FULLUNDERWRITING",
"tobaccoPremiumBasis": "SMOKER",
"approvedFaceAmount": 250000,
"approvedFaceAmountMaximum": 250000,
"riders": [
{
"type": "Rider_ABRTRM",
"approvedRiderFaceAmountMaximum": 100000
}
],
"exclusionReview": [
{
"description": "Aviation Activities",
"reasonCode": "AVIATION"
}
]
},
"identifiers": [
{
"identifier": "zlCaseId",
"value": "CA0001296422"
}
]
}
application/json
Validate Systematic Program Transaction
post
Path Parameters
planCodestringrequired
policyNumberstringrequired
Body
application/json
Body
application/json
SystematicProgramSubmitRequest
correlationIdstring
The unique ID to track transaction request across all systems
Example:657b717b7dcf554abf9ef067
effectiveDatestring(date)required
Date (with pattern “yyyy-mm-dd”) when the transaction was originally scheduled or expected to happen, can be a non-business day
Match pattern:([0-9]{4})-([0-9]{2})-([0-9]{2})
reverseInitiatorboolean
Property to isolate source transaction(s) that initiated the reversal
authorizationManualboolean
Indicates manual authorization handling may apply for this submission
isFractionalAmountAuthorizedboolean
Indicates whether fractional amount authorization applies for this systematic program update
contactMFAobject
Contact channels for multi-factor authentication on systematic program transactions
Show Child Parameters
agentobject
Named participant (e.g. servicing agent or policy holder context on the request)
Show Child Parameters
policyHolderobject
Named participant (e.g. servicing agent or policy holder context on the request)
Show Child Parameters
taxWithholdingInstructionsarray[object]
Show Child Parameters
fundAllocationobject
Show Child Parameters
fundDistributionsarray[object]
Show Child Parameters
featureTransactionProductobject
Product-level transaction classification accompanying the systematic program request
Show Child Parameters
submittedDatestring(date-time)
When the transaction was submitted (ISO-8601)
Example:2026-02-27T11:55:17Z
currencystring
ISO 4217 currency code
Example:USD
systematicProgramobjectrequired
Show Child Parameters
caseIdstring
Zinnia Live Case ID
Example:CA0000007389
externalTransactionIdstring
Transaction ID from external system
Example:A12345
externalArrangementIdstring
Arrangement ID from external system
Example:B45678
Response
application/json
Response
application/json
Success
TransactionResponse
statusstring
Allowed values:successfailure
errorarray[object]
Show Child Parameters
quoteResponseobject
post/policy/v1/transactions/{planCode}/{policyNumber}/systematicprograms/validation
Authentication
Path Parameters
Body
{
"effectiveDate": "effectiveDate",
"systematicProgram": {
"paymentForm": "DTCC",
"arrangementType": "PAYMENT"
}
}
application/json
Submit Systematic Program Transaction
post
Path Parameters
planCodestringrequired
policyNumberstringrequired
Body
application/json
Body
application/json
SystematicProgramSubmitRequest
correlationIdstring
The unique ID to track transaction request across all systems
Example:657b717b7dcf554abf9ef067
effectiveDatestring(date)required
Date (with pattern “yyyy-mm-dd”) when the transaction was originally scheduled or expected to happen, can be a non-business day
Match pattern:([0-9]{4})-([0-9]{2})-([0-9]{2})
reverseInitiatorboolean
Property to isolate source transaction(s) that initiated the reversal
authorizationManualboolean
Indicates manual authorization handling may apply for this submission
isFractionalAmountAuthorizedboolean
Indicates whether fractional amount authorization applies for this systematic program update
contactMFAobject
Contact channels for multi-factor authentication on systematic program transactions
Show Child Parameters
agentobject
Named participant (e.g. servicing agent or policy holder context on the request)
Show Child Parameters
policyHolderobject
Named participant (e.g. servicing agent or policy holder context on the request)
Show Child Parameters
taxWithholdingInstructionsarray[object]
Show Child Parameters
fundAllocationobject
Show Child Parameters
fundDistributionsarray[object]
Show Child Parameters
featureTransactionProductobject
Product-level transaction classification accompanying the systematic program request
Show Child Parameters
submittedDatestring(date-time)
When the transaction was submitted (ISO-8601)
Example:2026-02-27T11:55:17Z
currencystring
ISO 4217 currency code
Example:USD
systematicProgramobjectrequired
Show Child Parameters
caseIdstring
Zinnia Live Case ID
Example:CA0000007389
externalTransactionIdstring
Transaction ID from external system
Example:A12345
externalArrangementIdstring
Arrangement ID from external system
Example:B45678
Response
application/json
Response
application/json
Success
TransactionAcceptedResponse
correlationIdstring
Unique identifier which used by every system to trace the request
Example:3a2a3435-2089-4b81-9959-e0d569ccf4f0
caseIdstring
Zinnia Live Case ID
Example:CA0000369469
caseStatusstring
Zinnia Live Case Status
Example:IN_PROGRESS
pdfIdstring
Identifier for the generated or associated PDF document (e.g. OnBase document number). Returned on systematic program setup and update submit when available.
Example:DOC-10004567
post/policy/v1/transactions/{planCode}/{policyNumber}/systematicprograms
Authentication
Path Parameters
Body
{
"effectiveDate": "effectiveDate",
"systematicProgram": {
"paymentForm": "DTCC",
"arrangementType": "PAYMENT"
}
}
application/json