--- title: "Rider" url: "https://developers.zinnia.com/apis/policy-service-0-1-0/versions/8306e031-b41c-452a-a7ed-d73d65602086/schemas/Rider" --- > Full API specification: https://developers.zinnia.com/apis/policy-service-0-1-0/versions/8306e031-b41c-452a-a7ed-d73d65602086.md # Rider ## OpenAPI definition ```yaml openapi: 3.0.0 info: title: Policy Service version: 0.0.21 servers: - url: https://qa.api.zinnia.io components: schemas: RiderType: type: string enum: - BASE - RIDER - BASEINCREASE - INTEGRATEDRIDER - RIDERINCREASE - BENEFIT - DISCOUNT - OTHER - UNKNOWN UnderwritingStatus: type: string enum: - APPROVED - DECLINED Status: type: string enum: - ACTIVE - TERMINATED - PENDING - SUSPENDED RiderParticipant: type: object properties: insuredId: type: string description: A unique identifier assigned to the insured individual within the system who was covered under this rider example: Party_PI_1 insuredAgeAtIssue: type: number description: The age of the insured at the time the rider was issued example: 50 format: int32 PartyRiderParticipant: type: object properties: partyId: type: string description: A unique identifier assigned to the party insured within the system who was covered under this rider example: Party_PI_1 partyAgeAtIssue: type: number format: int32 description: The age of the insured at the time the rider was issued example: 50 riskClass: type: string enum: - ULTRANONTOBACCO - ELITENONTOBACCO - PREFERREDNONTOBACCO - STANDARDNONTOBACCO - STANDARDTOBACCO - STANDARDAGGREGATE - SUBSTANDARDNONTOBACCO - SUBSTANDARDTOBACCO - STANDARDPLUSNONTOBACCO - PREFERREDTOBACCO - STANDARDCONVERSIONTOBACCO - STANDARDCONVERSIONNONTOBACCO description: The Risk Class refers to the underwriting category assigned to an applicant based on their health, lifestyle, and medical history, which determines their premium rates for a life insurance policy. Insurers use risk classifications to assess mortality risk and price policies accordingly. substandardRating: type: string enum: - TABLEA - TABLEB - TABLEC - TABLED - TABLEE - TABLEF - TABLEG - TABLEH - TABLEI - TABLEJ - TABLEK - TABLEL - TABLEM - TABLEN - TABLEO - TABLEP - NONETABLE description: A Substandard Rating (also called Table Rating) is assigned to applicants who do not qualify for Standard or Preferred risk classes due to health conditions, lifestyle risks, or medical history. This rating results in higher premium costs because the insured presents a greater mortality risk. flatExtra: type: array items: $ref: "#/components/schemas/FlatExtra" RiderCharge: type: object properties: riderExerciseCharge: type: number description: One Time Rider Charge that will be Applied upon Rider Activation format: double example: 0 riderExerciseChargeRate: type: number description: The rate or percentage applied to calculate the charge for exercising the rider format: double example: 0 RiderCoverageLayer: type: object properties: coverageId: type: string description: The Coverage ID is a unique identifier assigned to a specific coverage type or benefit within an insurance policy. It helps insurance companies, agents, and policyholders track and differentiate multiple coverage components within a single policy. example: Base_Coverage coverageType: type: string enum: - BASE - RIDER - BASEINCREASE - INTEGRATEDRIDER - RIDERINCREASE - BENEFIT - DISCOUNT - OTHER - UNKNOWN description: The type of rider denoting if benefit is applicable to base coverage or a distinct coverage or addition to base coverage or a benefit without any coverage coverageName: type: string description: The Coverage Name in a life insurance policy refers to the specific title or label assigned to a coverage type within the policy contract. It helps insurers, agents, and policyholders identify, classify, and manage different coverage components in a policy. example: Base_Coverage productCode: type: string description: The Plan Code is a carrier-assigned alphanumeric identifier used to uniquely distinguish a specific insurance or annuity product, rate structure, version, and coverage layer within an insurer's portfolio. It is essential for policy administration, pricing, underwriting, and claims processing. example: EVGL1 coverageTerm: type: number format: int32 description: Coverage Term refers to the number of years that a life insurance policy or specific coverage component is intended to remain in force, providing protection to the insured. It defines the planned duration of insurance coverage, after which the coverage may expire, renew, or convert, depending on the product type. example: 1 approvedCoverageAmount: type: number format: double description: The Approved Coverage Amount refers to the specific amount of insurance coverage that has been approved by the insurer during the underwriting process. It represents the face amount (death benefit) the insurer has agreed to issue based on the applicant's risk profile, health, and other underwriting criteria. example: 10000 currentAmount: type: number format: double description: The Current Coverage Amount refers to the active or present death benefit or coverage value available under the policy at a specific point in time. It reflects any adjustments, policy changes, withdrawals, or loans that may have altered the original coverage amount. example: 300000 originalCoverageAmount: type: number format: double description: The Original Coverage Amount refers to the initial face value or death benefit of a policy at the time of issuance before any policy modifications, withdrawals, loans, or benefit reductions. It represents the starting coverage amount agreed upon when the policy was first issued. example: 300000 minimumCoverageAmount: type: number format: double description: The Minimum Coverage Amount at Each Coverage Level refers to the lowest permissible amount of insurance coverage allowed per policy layer, as set by the insurance carrier. It ensures policies remain financially viable and comply with regulatory and underwriting standards. example: 10000 maximumCoverageAmount: type: number format: double description: "The Maximum Coverage Amount at Each Coverage Level refers to the highest permissible amount of insurance coverage allowed per policy layer, as set by the insurance carrier. " example: 10000000 grossDeathBenefitAmount: type: number format: double description: The Gross Death Benefit per Coverage Layer refers to the total pre-deduction death benefit amount assigned to each specific coverage layer within a policy. It represents the sum of all base coverage amounts, riders, and enhancements before applying policy adjustments such as loans, withdrawals, or unpaid premiums. example: 300000 lowDeathBenefitAmount: type: number format: double description: Low Death Benefit refers to the lowest possible death benefit guaranteed within each specific coverage component of a policy. This ensures that beneficiaries receive at least a minimum death benefit regardless of market performance, policy changes, or withdrawals. example: 300000 coverageChangeAmount: type: number format: double description: The Coverage Change Amount refers to the specific increase or decrease in coverage that occurs within a life insurance policy due to policyholder requests, automatic adjustments, or insurer-initiated changes. This amount reflects the difference between the original or prior coverage amount and the new coverage amount after the change takes effect. example: 3000000 coverageEffectiveDate: type: string format: date description: The Coverage Effective Date refers to the date when an increase in coverage or a new coverage component officially takes effect in a life insurance policy. It marks the beginning of the insured’s eligibility for the new or increased benefits. example: 2023-01-01 coverageChangeEffectiveDate: type: string format: date description: The Coverage Change Effective Date (for a decrease in coverage) refers to the date when the reduced coverage amount officially takes effect in a life insurance policy. It marks the point from which the new lower coverage amount applies. example: 2023-01-01 coverageTerminationDate: type: string format: date description: The Coverage Termination Date refers to the date when a policy's coverage officially ends, meaning the insured is no longer protected under the contract. After this date, no benefits or claims can be paid unless reinstatement is an option. example: 2023-01-01 unitOfCoverage: type: number format: double description: "The Unit of Coverage refers to the measurement standard used to define the amount of coverage provided under a life insurance policy. It helps insurers calculate premiums, determine benefit payouts, and structure policies consistently.In life insurance, the unit of coverage is typically measured per $1,000 of face amount. " example: 300 valuePerUnitOfCoverage: type: number format: double description: The Value per Unit of Coverage refers to the monetary worth of each unit of coverage in a life insurance policy, which is used for premium calculations, benefit payouts, and policy adjustments. This value helps insurers standardize pricing and policy structures.In life insurance, the value per unit represents the cost per $1,000 of coverage or payout per unit of death benefit.In annuities, it determines the payout per annuity unit or per $1,000 of account value. example: 1000 guidelineSinglePremium: type: number format: double description: The Guideline Single Premium (GSP) is the maximum single premium payment that can be made into a life insurance policy without causing it to lose its tax-advantaged status as life insurance under IRS guidelines. It is determined based on IRS regulations and ensures that the policy remains compliant with Section 7702 of the Internal Revenue Code. example: 65068.27 guidelineLevelPremium: type: number format: double description: The Guideline Level Premium (GLP) is the maximum total premium that can be paid over time into a life insurance policy without violating IRS regulations under Section 7702. It ensures that a policy retains its tax-advantaged status as life insurance and does not become classified as a Modified Endowment Contract (MEC). example: 4695.39 sevenPayPremium: type: number format: double description: The 7-Pay Premium refers to the maximum cumulative premium that can be paid into a life insurance policy during the first seven years without causing the policy to become a Modified Endowment Contract (MEC). It is part of the 7-Pay Test, which ensures that life insurance policies do not become overfunded and lose their tax advantages. example: 19807.51 modalPremium: type: number format: double description: Modal Premium refers to the actual premium amount a policyholder pays based on the selected billing frequency (mode)—such as monthly, quarterly, semiannual, or annual. It represents the current periodic payment due for the base coverage and any attached riders under a life or annuity insurance policy. example: 1000 cumulativeModalPremium: type: number format: double description: Cumulative Modal Premium refers to the sum of actual premium amount a policyholder pays based on the selected billing frequency (mode)—such as monthly, quarterly, semiannual, or annual. It represents the sum of current periodic payment due for the base coverage and any attached riders under a life or annuity insurance policy. example: 1000 coverageTargetPremium: type: number format: double description: Coverage Target Premium refers to the designated premium amount on a life insurance policy that:Qualifies for full target-level commissions in the first policy year, and Forms the basis for renewal commissions in subsequent policy years.Note - This is modal premium value example: 300000 annualPremium: type: number format: double description: The annual premium is the total amount you would pay for a full year of life insurance or annuity if you made just one payment per year. example: 1000 overdueModalPremium: type: number format: double description: refers to a scheduled premium payment that was not received or applied by its due date, based on the policy’s modal frequency (e.g., monthly, quarterly, semi-annual, or annual). It represents a missed payment obligation that remains outstanding and may trigger administrative or policy-level actions example: 1000 Base: type: object properties: currentBase: type: number format: double example: 14.32 description: Tracked againist Account Value and will be updated on every Anniversary Incremented by gross premiums and credit enhancements. Set to Investment Value if rider is issed post contract issue. Adjusted for withdrawals. Reset on Anniversaries ratchetBase: type: number format: double description: Tracked againist Account Value and will be updated on every Anniversary Incremented by gross premiums and credit enhancements. Set to Investment Value if rider is issed post contract issue. Adjusted for withdrawals. Reset on Anniversaries. example: 19.35 growthBase: type: number format: double description: Incremented by gross premiums and credit enhancements. Set to Investment Value if rider is issed post contract issue. Adjusted for withdrawals. Reset on Anniversaries by crediting interest based on the interest rate in the Growth Factor Calculation equation box. example: 15.65 deferralBonus: type: number format: double description: The Deferral Bonus is configured a percent of a Deferred Bonus Base. It is set to the value on Feature Change, Premium, Annual Processing, GMWB Interest Adjustment transactions example: 12.65 deferralBonusBase: type: number format: double description: Captures the basis for calculating the Deferral Bonus.Base used to calculate the annual Deferral Bonus. Parameters defined in the Deferral tab (GMWB). Incremented by gross premiums. If GMDB feature added post issue, then set to Investment Value. Adjusted for withdrawals. Reset on Contract Anniversaries equal to the Deferral Bonus Base Reset equation box. Stored in the Transaction Log table. example: 13.12 simpleInterestBase: type: number format: double description: Incremented by gross premiums. Initialized to the Investment Value if GMDB added post issue. Adjusted for excess withdrawals. Set to Investment Value on Spousal Continuation. example: 14.21 required: - currentBase - ratchetBase - growthBase - deferralBonus - deferralBonusBase - simpleInterestBase FlatExtra: type: object properties: flatExtraType: type: string enum: - TEMPORARY - PERMANENT description: A Flat Extra is an additional dollar amount added to the base premium for a life insurance policy due to increased risk factors. Insurers apply Flat Extras on top of standard risk classifications (e.g., Preferred, Standard, or Substandard ratings).Flat Extras can be classified into two types "Temporary Flat Extra" and "Permanent Flat Extra" flatExtraDuration: type: number description: The Flat Extra Duration refers to the length of time a Flat Extra premium charge is applied to a life insurance policy. This duration depends on whether the Flat Extra is temporary or permanent, and it is determined by the insurer based on the risk factor associated with the insured format: int32 example: 0 flatExtraAmount: type: number description: The Flat Extra Amount refers to an additional charge per $1,000 of coverage that an insurer applies to a life insurance policy due to an increased risk factor. This extra cost is added on top of the standard premium and can be temporary or permanent, depending on the nature of the risk format: double example: 0 flatExtraStartDate: type: string description: The Flat Extra Start Date refers to the date when an additional, fixed premium charge (Flat Extra) begins on a life insurance policy. This charge is typically applied due to an increased underwriting risk, such as hazardous occupations, high-risk hobbies, or medical conditions format: date example: 2023-01-01 Rider: type: object properties: timestamp: type: string format: date-time description: TBD example: 2023-01-01T12:00:00.000Z type: $ref: "#/components/schemas/RiderType" riderName: type: string example: Chronic Illness Accelerated Death Benefit Rider description: The specific name of the rider as designated by the insurance company. For example - Terminal Illness Accelerated Death Benefit riderElected: type: string description: Indicates the election status of the rider on the policy, specifying whether the policyholder has formally elected to include the rider example: ELECTED riderCode: type: string description: A unique identifier or alphanumeric code assigned to the rider example: EVGLHR underwritingStatus: $ref: "#/components/schemas/UnderwritingStatus" unbornChildIndicator: type: boolean description: This will be set to yes if there is no Child rider insured to support Unborn Child qualifiedAdditionalBenefit: type: boolean description: Indicates whether the rider provides a qualified benefit under IRS or insurance regulations effectiveDate: type: string format: date description: Date on which Rider is selected and becomes effective on the policy example: 2023-01-01 exerciseDate: type: string format: date description: The date the policyholder elects to use or activate the rider benefit example: 2023-01-01 terminationDate: type: string format: date description: The date on which the rider coverage ends/ is terminated example: 2023-01-01 status: $ref: "#/components/schemas/Status" coverageId: type: string example: Rider_EVGLCHR description: An unique identifier assigned to the rider coverage within an insurance coverage or policy layer amount: type: number description: The total benefit amount the rider provides (separate from the base policy’s coverage.) example: 0 annualBenefitAmount: type: number description: The maximum benefit amount of the benefit base, policyholder can withdraw each year example: 0 format: double riderBenefitAmount: type: number description: The Total Benefit Amount represents the maximum guaranteed amount available under the annuity rider over the life of the contract/rider example: 0 format: double riderBenefitPercent: type: number description: The fixed percentage applied to the Rider Benefit Amount to calculate the annual guaranteed benefit amount example: 100 format: double minimumRiderBenefitAmount: type: number description: Refers to a guaranteed payout to a beneficiary upon the death of the annuitant, regardless of the contract investment performance, as long as the annuity is in the accumulation phase. Used for Variable annuities example: 0 format: double growthIncomeBenefitAmount: type: number description: The Growth Income Benefit value represents the guaranteed income base established under a Guaranteed Minimum Income Benefit (GMIB) rider. It is used to calculate the lifetime income payments the annuitant is entitled to upon annuitization, regardless of the contract actual account value. example: 0 format: double riderStoredIncomeBalance: type: number description: Amount that can be withdrawn without reducing the yearly or Lifetime rider benefit amount example: 0 format: double riderParticipant: description: Note - Use riderParticipants field instead of riderParticipant type: array items: $ref: "#/components/schemas/RiderParticipant" additionalBenefitUsageCount: type: number format: int32 description: The number of times the additional benefit has been used. example: 0 riderParticipants: type: array items: $ref: "#/components/schemas/PartyRiderParticipant" charge: $ref: "#/components/schemas/RiderCharge" maximumChronicIllnessBenefitPercentage: type: number description: The highest percentage of the death benefit or face amount that can be taken for chronic illness coverage example: 2.5 maximumPeriodicPaymentPeriod: type: number description: The maximum duration over which payments can be made under the rider ( in Months) claimStatus: type: boolean description: The current status of a claim filed under the rider nextEvaluationDate: type: string format: date description: The date of the next scheduled review or re-evaluation of an ongoing claim (applicable for riders like chronic illness). example: 2023-01-01 riderPaymentDate: type: string format: date description: The date the benefit payout under the rider is to be disbursed to the policyholder or beneficiary example: 2023-01-01 terminalRiderPaymentAmount: type: number description: The amount paid under the rider benefit.(during a given payout cycle) example: 0 riderMinimumPaymentAmount: type: number description: Deprecated - kept for backwards compatibility example: 0 maximumCriticalIllnessBenefitPercentage: type: number description: The highest percentage of the policy’s face amount that can be accessed under the critical illness rider example: 0 tierOneMaximumCriticalIllnessBenefitPercentage: type: number description: The percentage of the benefit payable under Tier 1 of the critical illness structure (e.g., for mild conditions). example: 0 tierOneMaximumCriticalIllnessBenefitAmount: type: number description: The maximum dollar amount payable under Tier 1 benefits example: 0 tierTwoMaximumCriticalIllnessBenefitPercentage: type: number description: The percentage of the benefit payable under Tier 2(usually for more severe conditions.) example: 0 tierTwoMaximumCriticalIllnessBenefitAmount: type: number description: The maximum dollar amount payable under Tier 2 benefits. example: 0 tierOneCriticalRiderPaymentDate: type: string format: date description: The date on which the Tier 1 critical illness rider benefit payment is scheduled or was made example: 2023-01-01 tierOneCriticalRiderPaymentAmount: type: number description: The amount of benefit paid under the Tier 1 critical illness example: 0 tierTwoCriticalRiderPaymentDate: type: string format: date description: The date on which the Tier 2 critical illness rider benefit payment is scheduled or was made example: 2023-01-01 tierTwoCriticalRiderPaymentAmount: type: number description: The amount of benefit paid under the Tier 2 critical illness example: 0 coverageLayers: type: array items: $ref: "#/components/schemas/RiderCoverageLayer" remainingBenefit: type: number format: double description: The remaining benefit amount for the rider. Incremented by Premiums and adjusted by withdrawals. example: 10.51 additionalBenefitUsedUp: type: boolean description: Indicates whether the ADL benefit is utilised on the contract. totalBenefit: type: number format: double description: The total guaranteed value the contract owner is entitled to at the end of the GMAB holding period — assuming no disqualifying withdrawals or events. example: 5.17 payoutOption: type: string enum: - SINGLE - JOINT description: Single or Joint Payout (not driven by Owners on the policy, even a jointly owned policy can have single as an option. Used in configuration to set different GMWB benefits for Single and Joint GMWB Amount Types benefitPercent: type: number format: double description: Ties to Withdrawal Reset Benefit % Annual Limit on Calender Processing if GMWB Anniversary Base reset is elected. Equals result of GMWB Benefit % equation box in Withdrawal tab (GMWB) Ku - Payout Factor Percentage of the benefit base that will be available for withdrawal each year example: 1.23 annualBenefitLimit: type: number format: double description: GMWB Annual Limit, The total amount that can be withdrawn as a benefit of this rider in any given policy year, regardless of whether or not there is sufficient account value. It is also the annual limit on amounts that can be withdrawn without adversely affecting future annual and lifetime benefits from the rider.this amount will be impacted during Reset or Withdrawals or Premium events example: 3.43 currentAnnualLimit: type: number format: double description: " GMWB Annual Limit, The total amount that can be withdrawn as a benefit of this rider in any given policy year, regardless of whether or not there is sufficient account value. It is also the annual limit on amounts that can be withdrawn without adversely affecting future annual and lifetime benefits from the rider.this amount will be impacted during Reset or Withdrawals or Premium events" example: 5.45 remainingAnnualLimit: type: number format: double description: The GMWB amount still available for withdrawal in the current Contract Year without creating an "Excess Withdrawal" situation. example: 6.75 hypotheticalAnnualLimit: type: number format: double description: During the riders accumulation phase (before it is exercised), a hypothetical annual withdrawal limit is calculated and displayed on statements to inform the policyholder and assist in their decision to exercise the rider example: 8.95 phase: type: string enum: - ACCUMULATION - INCOME description: Indicator for whether the phase is Accumulation (not activated, benefit base is still accruing) or Income (annual limit calculated, benefit bases stop growing). Default value = Accumulation lastResetDate: type: string format: date description: User initiates the Reset, Variables product example: 2023-01-01 base: $ref: "#/components/schemas/Base" ```