Search
K
Policy

Parties

get
https://api.zinnia.io/policy/v1/policies/{planCode}/{policyNumber}/parties

Query Parameters

partyRolestring

Allowed values:OwnerJointOwnerAnnuitantJointAnnuitantPayeePayorThirdPartyDesigneePrimaryBeneficiaryContingentBeneficiaryGrantorTrusteePowerOfAttorney

partyIdstring

Path Parameters

planCodestringrequired
policyNumberstringrequired

Response

application/json

OK

partyTypestring

Allowed values:INDIVIDUALORGANIZATIONTRUST

partyRoleIdstring

TBD

parentPartyIdstring

The Parent Party ID is a unique identifier used to establish a hierarchical or relational link between multiple related parties within a life insurance or annuity contract. It is particularly useful in complex ownership or beneficiary structures, such as: Trust-owned policies, Multiple contingent beneficiaries linked to a single primary beneficiary, Parties acting in legal or fiduciary roles (e.g., grantors, trustees, custodians)

Example:1

beneficiaryPercentagenumber(double)

Deprecated - kept for backward compatibility; instead use partyPercentage. The benefit percentage of the beneficiary

Example:100

agentPercentagenumber(double)

Deprecated - kept for backward compatibility; instead use partyPercentage. Commission percentage for each agent

Example:100

agentExternalIdstring

The Id which user enters(Id validated in MCS) - Agent External ID and Compnay ID uniquely identifies the right Agent

Example:3160000751

agentTypestring

Allowed values:ACCOUNTMANAGERADDITIONALCOMPENSATIONRECIPIENTADVANCEDUNDERWRITINGCONSULTANTAGENCYORGENERALAGENTAGENCYDIRECTORAGENCYSUPERINTENDENTAGENCYVICEPRESIDENTAGENTORPRODUCERASSISTANTASSISTANTGROUPUNDERWRITERASSISTANTMANAGERASSISTANTVICEPRESIDENTASSISTANTVPCOMPLIANCEASSOCIATEAGENCYMANAGERASSOCIATEFINANCIALPLANNERASSOCIATEOFFICERMANAGERASSOCIATESALEDEVELOPMENTMANAGERINTRAININGASSOCIATESALESDEVELOPMENTMANAGERBANKBANKEMPLOYEEBRANCHMANAGERBROKERBROKERORDEALERBROKERAGEDIRECTORBROKERAGEGENERALAGENTCERTIFIEDFINANCIALPLANNERDISTRIBUTORFINANCIALCONSULTANTFINANCIALPLANNERMANAGINGDIRECTORMANAGINGGENERALAGENTOFFICEMANAGEROTHERPLATFORMREPQUALIFYINGOFFICERREGISTEREDFINANCIALPLANNERREGISTEREDREPRESENTATIVESALESDEVELOPMENTMANAGERSECONDLINEMANAGERSENIORADMINISTRATIVECONSULTANTSENIORADVANCEDUNDERWRITINGCONSULTANTSENIORFINANCIALPLANNERSENIORGROUPACCOUNTEXECUTIVESENIORGROUPSALESREPRESENTATIVESENIORPARTNERSENIORSALESDEVELOPMENTMANAGERSENIORVICEPRESIDENTSERVICINGBROKERSERVICINGONLYAGENTSOLICITORTEAMUNKNOWN

firstNamestring

The first name of the party/trustee

Example:Karen

middleNamestring

The middle name of the party/trustee

Example:Anne

lastNamestring

The last name of the party/trustee

Example:Bates

fullNamestring

The full name of the party/The legal name of the Trust/Organization

Example:Karen Anne Bates

prefixstring

Allowed values:MRMSMISSMRSDR

suffixstring

The suffix of the party name

Allowed values:JRSNSRIIIIIIIVVVIVII

genderstring

Allowed values:MALEFEMALEUNISEX

dateOfBirthstring(date)

The date of birth of the party

Example:2023-01-01

genderIdentitystring

Gender Identity refers to an individual’s self-identified internal sense of gender, which may differ from their sex assigned at birth. This value reflects how the individual personally defines their gender and may be expressed in free-text to allow for inclusivity and accuracy

Example:TBD

attainedAgeinteger(int32)

Age calculated by date of birth and Policy year

Example:55

birthCountrystring

Allowed values:USCARUEGZAGRNLBEFRESHUITROCHATGBDKSENOPLDEPEMXCUARBRCLCOVEMYAUIDPHNZSGTHJPVNCNTRINPKAFLKIRMADZTNLYGMSNMRMLGNBFNETGBJMULRSLGHNGCFTDCMCVSTGQGABSAOBBAXSDRWETSODJKETZUGBIMZZMMGREZWNAMWLSBWAGKMGWCDVGSHAWFOGLKYGIPTLUIEISALMTCYFIBGGGLTLVEEMDAMBYADSMUAHRSIBAMKXKCZSKLIBMGDFKBZGTSVHNNICRPMHTPRVIGSSXBQGPBOGYECGFPYMQSRUYANTCBLMFMSGUAQBNNRPGTOSBVUFJWFCKNUASKINCTVPFMPPWMHFMSSLCDMVCDOHKMOKHLATTKNJMBDTWMMKRKPLBJOSYIQKWSAOMAEILBHQABTNPTJTMAZGEUZAIPACIERKZKGCCMNBVSCIOWSTLTFYTPNSJTKUMEHMVCXNFCGMCVASZPSJEIMRSMEHMCWCSYEYDSUYUZR

citizenCountrystring

Allowed values:USCARUEGZAGRNLBEFRESHUITROCHATGBDKSENOPLDEPEMXCUARBRCLCOVEMYAUIDPHNZSGTHJPVNCNTRINPKAFLKIRMADZTNLYGMSNMRMLGNBFNETGBJMULRSLGHNGCFTDCMCVSTGQGABSAOBBAXSDRWETSODJKETZUGBIMZZMMGREZWNAMWLSBWAGKMGWCDVGSHAWFOGLKYGIPTLUIEISALMTCYFIBGGGLTLVEEMDAMBYADSMUAHRSIBAMKXKCZSKLIBMGDFKBZGTSVHNNICRPMHTPRVIGSSXBQGPBOGYECGFPYMQSRUYANTCBLMFMSGUAQBNNRPGTOSBVUFJWFCKNUASKINCTVPFMPPWMHFMSSLCDMVCDOHKMOKHLATTKNJMBDTWMMKRKPLBJOSYIQKWSAOMAEILBHQABTNPTJTMAZGEUZAIPACIERKZKGCCMNBVSCIOWSTLTFYTPNSJTKUMEHMVCXNFCGMCVASZPSJEIMRSMEHMCWCSYEYDSUYUZR

birthStatestring

Allowed values:AAAEALAPAKAZARASCACOCTDCDEFLGAGUHIIDILINIAKSKYLAMEMDMAMIMNMSMOMPMTNENVNHNJNMNYNCNDOHOKORPAPRRISCSDTNTXUMUTVTVAVIWAWVWIWY

doingBusinessAsstring

The name the organization is commonly known as

Example:TBD

abbreviatedNamestring

The shortened/abbreviated version of the organization`s name that is unique to the organization

Example:TBD

organizationCodestring

Code to Identify organization

Example:TBD

entityTypestring

Allowed values:SOLEPROPRIETORSHIPGENERALPARTNERSHIPLIMITEDPARTNERSHIPCCORPORATIONSCORPORATIONLIMITEDLIABILITYCOMPANYCHARITABLEORGANIZATIONESTATETRUSTCORPORATIONUNKNOWN

trustDatestring(date)

The trust agreement issued date to the party

Example:2023-01-01

amendedTrustDatestring(date)

The Amended Trust Date refers to the most recent date on which the trust agreement was formally amended or restated, particularly when the trust is designated as the owner or beneficiary of a life insurance or annuity policy

Example:2023-01-01

governingStateOfTruststring

Allowed values:AAAEALAPAKAZARASCACOCTDCDEFLGAGUHIIDILINIAKSKYLAMEMDMAMIMNMSMOMPMTNENVNHNJNMNYNCNDOHOKORPAPRRISCSDTNTXUMUTVTVAVIWAWVWIWY

trustTypestring

Allowed values:INDIVIDUALTRUSTCORPORATETRUSTTESTAMENTARYTRUSTINTERVIVOSTRUSTGRANTORTRUST

trustTitlestring

The title of the trustee

Example:TBD

trustAccessCodestring

Access code of the trustee

Example:TBD

preferredCommunicationTypestring

Allowed values:EMAILREGULARMAILPHONEFAXTEXTNOPREFERENCESPECIFIEDPOSTALOTHER

preferredAddressIndicatorstring

Deprecated - kept for backward compatibility; instead use preferredAddressIndicator under Address section

Example:1

preferredAddressIdstring

The Preferred Address ID refers to the unique identifier of the address designated as the primary or preferred address for a given party when multiple addresses are associated with that individual or entity. This ensures consistent use of the correct address for communication, correspondence, and recordkeeping

Example:1

preferredEmailIdstring

The Preferred Email ID refers to the unique identifier of the email address designated as the primary or preferred email contact for an individual or entity when multiple email addresses are on file

Example:1

preferredPhoneIdstring

The Preferred Phone ID refers to the unique identifier of the phone number designated as the primary contact number for a given individual or entity when multiple phone numbers are associated with the same party

Example:1

partyPercentagenumber(double)DEPRECATED

Party Percentage refers to the proportion of ownership, benefits, or responsibility assigned to a party within an insurance or annuity contract. It is used to distribute policy ownership, benefit payouts, commission sharing, or annuity payments among multiple parties

Example:12.1213

formerNameobject
Show Child Parameters
identificationsarray[object]
Show Child Parameters
taxWithholdingsarray[object]
Show Child Parameters
partyStatusstring

Allowed values:APPROVEDNOTAPPROVEDPROCESSED

isPartyBeneficiaryNonNaturalnumber

A boolean field that indicates whether the beneficiary of a Party (when the Party is a Trust) is Non-Natural. This data point is captured for taxation purposes, as Trusts established for individuals are taxed differently from those benefiting entities

Allowed values:true

isIrrevocablenumber

An indicator if the beneficiary is irrevocable. If yes, when doing any changes the beneficiary must also sign forms

Allowed values:true

isRequiredMinimumDistributionDesignatednumber

An indicator if the beneficiary is designated to be included in Joint RMD calculations

Allowed values:true

lastContactDatestring(date)

Last Contact Date refers to the most recent date on which there was a direct or system-recorded interaction with a party (individual or entity) associated with a policy or contract. This party may be a policyholder, insured, beneficiary, payor, agent, or any other role relevant to life and annuity products.

Example:2023-01-01

beneficiaryShareMethodstring

The Beneficiary Share Method refers to the approach used to allocate the death benefit (or other payouts) among multiple beneficiaries listed under a policy or contract. It determines how the proceeds are divided in the event of the insureds death and is typically defined during policy setup or updated via a beneficiary change request.

Allowed values:PERSTIRPESDISTRIBUTION

partyIdstring

Party ID is a unique identifier assigned to a party (individual or entity) involved in an insurance or annuity contract. This identifier helps ensure accurate data exchange and tracking across insurance transactions

Example:Party_PB_Primary_Bene_1

addressesarray[object]

Array of addresses associated with the party

Show Child Parameters
phonesarray[object]

Array of phone numbers associated with the party

Show Child Parameters
emailsarray[object]

Array of emails associated with the party

Show Child Parameters
bankDetailsarray[object]

Array of bank accounts associated with the party

Show Child Parameters
deathDetailsobject
Show Child Parameters
impairmentDetailsobject
Show Child Parameters
timestampstring(date-time)required

TBD

Example:2023-01-01T12:00:00.000Z

policyNumberstringrequired

Policy number

Example:ZH12345678

customerIdstringrequired

TBD

Example:0017b000010N4bCAAS

insuredobjectrequired
Show Child Parameters
versionnumber(int32)required

Example:1

get/policy/v1/policies/{planCode}/{policyNumber}/parties
 
application/json

Policy Illustration Information

get
https://api.zinnia.io/policy/v1/policies/{planCode}/{policyNumber}/lpspayload

Path Parameters

planCodestringrequired
policyNumberstringrequired

Response

application/json

OK

LPSPayloadResponse

attributesobjectrequired

Attributes

Show Child Parameters
accountValueobjectrequired

Account Value

Show Child Parameters
testValueobjectrequired

Test Value

Show Child Parameters
deathBenefitobjectrequired

Death Benefit

Show Child Parameters
coverageValueobjectrequired

Coverage Value

Show Child Parameters
coveragesarray[object]required

Array of Coverages

Show Child Parameters
partiesarray[object]required

Array of Parties

Show Child Parameters
policyFeeobjectrequired

Policy Fee

Show Child Parameters
featuresobjectrequired

Features

Show Child Parameters
fundAllocationsarray[object]required

Array of Fund Allocations

Show Child Parameters
fundsarray[object]required

Array of Funds

Show Child Parameters
matchSegmentobjectrequired

Match Segment

Show Child Parameters
loanSegmentsarray[object]required

Array of Loan Segments

Show Child Parameters
arrangementsarray[object]required

Array of Arrangements

Show Child Parameters
get/policy/v1/policies/{planCode}/{policyNumber}/lpspayload
 
application/json

Features

get
https://api.zinnia.io/policy/v1/policies/{planCode}/{policyNumber}/features

Path Parameters

planCodestringrequired
policyNumberstringrequired

Response

application/json

OK

featureTypestring

Allowed values:FREELOOKLAPSEASSESSMENTLAPSEPROTECTIONREINSTATEMENTRATELOCKANNUITIZATIONNONFORFEITUREOPTIONCONVERSIONDISCOUNTBILLINGCUSTOMFEATURE

featureIndicatornumber

A Feature Indicator in life insurance and annuities refers to a binary flag (Yes/No, True/False, or Enabled/Disabled) that signifies whether a specific policy feature, rider, or benefit is included in the contract. It helps insurers, agents, and policyholders quickly identify which optional or standard benefits apply to a policy

Allowed values:true

featureOptionstring

A Feature Option in life insurance and annuities refers to the specific choices or variations available within a policy feature, allowing customization based on the policyholder’s needs

Allowed values:LIFEONLYJOINTLIFEONLYJOINTANDSURVIVORPERIODCERTAINAMOUNTCERTAINLIFEWITHPERIODCERTAINLIFEWITHCASHREFUNDLIFEWITHINSTALLMENTREFUNDAUTOMATICPOLICYLOANREDUCEDPAIDUPAGEFACEAMOUNTLEGALOPERATIONALCOLLATERALLYASSIGNEDUNSPECIFIED

reducedPaidUpFaceAmountnumber(double)

Reduced Paid-Up Face Amount is the new, lower death benefit that results when a policyholder elects the Reduced Paid-Up (RPU) insurance option on a permanent life insurance policy. Under this option, the policyholder uses the accumulated cash value of their policy to purchase a fully paid-up policy—meaning no further premiums are required—but with a reduced face amount compared to the original coverage

Example:46.49

startDatestring(date)

Start date of the feature

Example:2023-01-01

endDatestring(date)

End date of the feature

Example:2023-01-01

statusnumber

A Feature Status in life insurance and annuities indicates the current state or activation condition of a specific feature within a policy or contract. It reflects whether a feature is active, inactive, pending, or restricted, helping insurers, agents, and policyholders track policy functionality

Allowed values:true

periodnumber(int32)

The Period of Feature in life insurance and annuities refers to the duration for which a specific feature or benefit is available, active, or applicable within a policy or contract. It defines the time frame in which a feature can be used, exercised, or remains valid

Example:30

effectiveDatestring(date)

Effective date of the feature

Example:2023-01-01

totalRequiredAmountnumber(double)

The Total Minimum Required Amount refers to the lowest financial threshold needed to activate, maintain, or utilize a specific insurance or annuity feature. This can include minimum premiums, account balances, contributions, or fees necessary to keep the policy or benefit in force

Example:0

totalMinimumRequiredAmountnumber(double)

Min (This is if Carrier Acceot Min) - This is the Amount needed to reactivate the Policy (If there is an Outstanding Loan on the Policy Min Required Loan Balance will be part of this Amount)

Example:0

paymentAmountnumber(double)

The Payment Amount for a Feature refers to the specific cost required to activate, maintain, or utilize a particular policy feature or rider in a life insurance or annuity contract. This amount can be a one-time payment, recurring charge, or deducted from policy values depending on the feature type

Example:46.49

exclusionAmountnumber(double)

The Fixed Exclusion Amount in the annuitization feature of an annuity refers to the portion of each annuity payment that is considered a return of the original investment (principal) and is therefore excluded from taxable income. This amount helps annuitants determine their tax liability on annuity payments

Example:46.49

yearToDatePaymentAmountnumber(double)

The YTD Payment Amount for a Feature refers to the total amount paid or received for a specific policy feature from the beginning of the calendar year to the current date. This amount is commonly tracked for premiums, rider fees, annuity payouts, withdrawals, and other benefit-related transactions

Example:46.49

exclusionRationumber(double)

The Exclusion Ratio in annuitization refers to the portion of each annuity payment that is considered a return of the original investment (principal) and is therefore excluded from taxable income. It determines how much of an annuity payment is taxable and how much is tax-free.

Example:46.49

totalPaymentAmountnumber(double)

The Total Payment Amount of a Feature refers to the cumulative cost or sum of all payments made over time for a specific feature in a life insurance or annuity contract. This can include premiums, rider fees, annuity payouts, or benefit-related charges

Example:46.49

jointLivesPercentageToSurvivornumber(double)

Joint Lives % to Survivor refers to the percentage of annuity payments that continue to the surviving annuitant after one of the joint annuitants passes away. It applies to Joint & Survivor Annuities, ensuring ongoing income for the surviving spouse or beneficiary.

Example:100

underwritingDecisionnumber

The Reinstatement Underwriting Decision refers to the evaluation process and approval or denial of a reinstatement request for a lapsed life insurance policy or annuity contract. When a policy lapses due to non-payment, the insurer requires underwriting to determine if the policy can be reinstated based on financial, medical, and risk factors

Allowed values:true

approvalDatestring(date)

The Approval Date for a Feature refers to the official date on which an insurance company authorizes and activates a specific feature, rider, or benefit within a life insurance policy or annuity contract. This date marks when the feature becomes effective and available for use by the policyholder or annuitant

Example:2023-01-01

featureIdstring

Unique identifier of feature sub-type for "custom feature

Example:123

frequencystring

Allowed values:DAILYEVERYTWOWEEKSMONTHLYSEMIANNUALQUARTERLYANNUALSINGLEPAYMENT

paymentFormstring

Allowed values:DTCCCREDITCARDACHCHECKWIREEXCHANGE

featureSubTypestring

Gives the sub type of the feature type "Custom Feature

Allowed values:MULTIPLEPOLICYDISCOUNTCONTROLBUSINESSINDICATORRESTRICT

timestampstring(date-time)

TBD

Example:2023-01-01T12:00:00.000Z

get/policy/v1/policies/{planCode}/{policyNumber}/features
 
application/json

Distribution of Investments

get
https://api.zinnia.io/policy/v1/policies/{planCode}/{policyNumber}/distribution

Query Parameters

versioninteger

Path Parameters

planCodestringrequired
policyNumberstringrequired

Response

application/json

OK

investmentTypestring

Allowed values:INVESTMENTFUNDINVESTMENTMODEL

modelNamestring

Elect from available … If Owner picks and Model as an investment option

Example:TBD

modelIdstring

The corresponding Model Id of the elected model

Example:TBD

fundAllocationsInvestmentsarray[object]
Show Child Parameters
fundsarray[object]
Show Child Parameters
matchSegmentobject
Show Child Parameters
loanSegmentsarray[object]
Show Child Parameters
get/policy/v1/policies/{planCode}/{policyNumber}/distribution
 
application/json

Coverage

get
https://api.zinnia.io/policy/v1/policies/{planCode}/{policyNumber}/coverage

Path Parameters

planCodestringrequired
policyNumberstringrequired

Response

application/json

OK

PolicyCoverage

totalCoverageAmountnumber(double)

The Total Coverage Amount refers to the maximum benefit or sum insured that a policyholder or beneficiary is entitled to receive under a life insurance contract. It represents the total financial protection provided by the policy

Example:300000

cumulativeGrossDeathBenefitAmountnumber(double)

The Cumulative Gross Death Benefit refers to the total amount payable to a beneficiary upon the insured or annuitant death, before any deductions such as loans, outstanding premiums, or surrender charges. It represents the gross value of the death benefit provided under a life insurance or annuity contract. It is cumulative gross death benefit of all the layers of base coverage (not including riders ).

Example:300000

netDeathBenefitnumber(double)

The Net Death Benefit refers to the actual amount paid to the beneficiary upon the insured or annuitant death, after deductions such as policy loans, unpaid premiums, withdrawals, or other charges

Example:300000

remainingDeathBenefitAmountnumber(double)

The Remaining Death Benefit Amount refers to the portion of the death benefit that is still available as of date for benefit payment to beneficiaries after a partial claim has been taken

Example:300000

minimumCoverageAmountnumber(double)

The Minimum Coverage Amount refers to the lowest amount of death benefit or policy coverage that an insurance company allows for a life insurance contract. It is the smallest sum insured that can be purchased under a specific product type

Example:10000

maximumCoverageAmountnumber(double)

The Maximum Coverage Amount refers to the highest amount of death benefit or policy coverage that an insurance company will issue under a life insurance contract. It represents the largest sum insured that an applicant can qualify for based on underwriting and financial eligibility

Example:10000000

coverageChangeEffectiveDatestring

The Earliest Coverage Change Date refers to the first possible date when a modification to an insurance policy can take effect. It defines the earliest point at which a policyholder can adjust coverage levels, add or remove riders, or make other contractual changes based on policy terms and conditions

Example:2023-01-01

coverageBandstring

In life insurance, a band refers to a coverage range or tier that affects premium rates, underwriting guidelines, or policy benefits. Insurance companies use coverage bands to determine pricing structures, offering lower per-unit costs for higher coverage amounts

Allowed values:BAND1BAND2BAND3BAND4BAND5BAND6BAND7

maximumAnnualCoverageChangeAllowedPerPolicyinteger(int32)

The Maximum Annual Coverage Change Allowed per Policy refers to the largest increase or decrease in coverage amount permitted within a single policy year, as defined by the insurance carrier. This limit is set to maintain policy stability, prevent excessive risk exposure, and ensure compliance with underwriting and policy guidelines

Example:1

minimumCoverageDecreaseAmountnumber(double)

The Minimum Coverage Amount Decrease refers to the smallest reduction in coverage that a policyholder is allowed to make per policy year, as defined by the insurance carrier. This ensures that policies remain viable and do not fall below the required minimum coverage limits

Example:10000

maximumCoverageDecreaseAmountnumber(double)

The Maximum Coverage Amount Decrease refers to the largest reduction in coverage that a policyholder is allowed to make per policy year, as defined by the insurance carrier. This ensures that policyholders can lower coverage if needed while maintaining a minimum required coverage amount

Example:290000

maximumAgeNumberCoverageAmountDecreaseinteger(int32)

The Maximum Age of No Coverage Amount Decrease refers to the age at which a policyholder can no longer reduce their coverage amount. This limit is set by the insurance carrier to maintain policy integrity and ensure sufficient death benefit protection, particularly for older policyholders

Example:80

coverageAmountDecreaseAllowedinteger(int32)

The Number of Coverage Amount Decrease Allowed Per Policy Year refers to the maximum number of times a policyholder is permitted to reduce their coverage amount within a single policy year. This limit is set by the insurance carrier to maintain policy stability and prevent excessive policy modifications

Example:120

minimumCoverageIncreaseAmountnumber(double)

The Minimum Coverage Amount Increase refers to the smallest increment by which a policyholder can raise their coverage amount within a policy year. This minimum threshold is set by the insurance carrier to ensure that coverage increases are financially viable and align with underwriting guidelines

Example:10000

maximumCoverageIncreaseAmountnumber(double)

The Maximum Coverage Amount Increase refers to the highest amount by which a policyholder can raise their coverage within a single policy year, as defined by the insurance carrier. This limit ensures that coverage increases remain manageable and are aligned with underwriting and financial justification

Example:9700000

maximumAgeNumberCoverageAmountIncreaseinteger(int32)

The Maximum Age of No Coverage Amount Increase refers to the oldest age at which a policyholder can request an increase in coverage. After reaching this age, the policyholder is no longer eligible to increase their coverage amount, as determined by the insurance carrier

Example:80

coverageAmountIncreaseAllowedinteger(int32)

The Number of Coverage Amount Increases Allowed Per Policy Year refers to the maximum number of times a policyholder can request an increase in coverage within a single policy year, as defined by the insurance carrier. This limit helps insurers manage risk exposure and maintain policy stability

Example:10

coverageLayersarray[object]
Show Child Parameters
get/policy/v1/policies/{planCode}/{policyNumber}/coverage
 
application/json