---
title: "ManageRiderRequest"
url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/schemas/ManageRiderRequest"
---

> Full API specification: https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84.md

# ManageRiderRequest

Self-serve request body for manage rider eligibility, validation, and submit endpoints (POST `/bpm/v1/policies/{planCode}/{policyNumber}/managerider/eligibilitycheck`, `/managerider/validation`, and `/managerider`). Assumes all referenced parties and rider participants already exist on the policy, identified by partyId only.

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Zinnia Policy Transactions API.
  version: 1.0.9
servers:
  - url: https://dev.api.zinnia.io
    description: DEV Environment
  - url: https://qa.api.zinnia.io
    description: QA Environment
components:
  schemas:
    ManageRiderExternalIdentifiers:
      type: object
      properties:
        externalTransactionId:
          type: string
          description: Transaction identifier assigned by the external/source system
            submitting the request
          example: test
        referenceNumber:
          type: string
          description: Additional reference number supplied by the external system for
            tracking purposes
          example: uniquetest1233
    ManageRiderTransactionReason:
      type: string
      enum:
        - ONETIMEPREMIUM
        - GRACEPERIODPREMIUM
        - REINSTATEMENTPREMIUM
        - EXCHANGE1035
        - SURRENDER
        - AMOUNTEXCESSTOMEC
        - AMOUNTEXCESSTOGUIDELINE
        - CURRENTVALUE
        - COSTBASIS
        - GUIDELINESINGLEPREMIUM
        - GUIDELINELEVELPREMIUM
        - SEVENPAYPREMIUM
        - TOTALYTDPREMIUMAMOUNT
        - FACEDECREASECOVERAGE
        - INITIALPREMIUMEXPIRATION
        - COMPLIANCE
        - NOTRANSACTIONREASON
        - STARTINGPRICE
        - LUMPSUM
        - FIVEYEARDEFERRAL
        - SPOUSALCONTINUATION
        - DISCOUNT
        - CONTROLBUSINESSINDICATOR
        - NATIONALCHANGEOFADDRESS
        - DATEOFDEATH
        - INITIALDEATHNOTIFICATION
        - PRODUCTDEFAULT
        - AMOUNT
        - GWBRIDERDISBURSEMENT
        - GWBPHASECHANGE
        - FREQUENCY
        - PREMIUMLOAN
        - PAYMENTDUEDATE
        - RIDERUPDATEGLWB
        - ACTUARIALPRESENTVALUE
        - JUVENILETOADULT
      description: Reason for initiating the manage rider transaction
      example: RIDERUPDATEGLWB
    ManageRiderRider:
      type: object
      description: A single rider being added, updated, or removed on the policy
      properties:
        action:
          $ref: "#/components/schemas/ManageRiderAction"
        riderId:
          type: string
          example: Rider_1
        riderCategory:
          $ref: "#/components/schemas/ManageRiderCategory"
        riderType:
          $ref: "#/components/schemas/ManageRiderType"
        optedForPolicy:
          $ref: "#/components/schemas/ManageRiderOptedForPolicy"
        effectiveDate:
          type: string
          format: date
          example: 2026-07-15
        exerciseDate:
          type: string
          format: date
          example: 2026-10-29
          description: Maps from the UI Exercise Date field
        riderStatus:
          type: string
          example: ACTIVE
        payoutOption:
          $ref: "#/components/schemas/ManageRiderPayoutOption"
        unbornChildIndicator:
          type: boolean
          nullable: true
          example: null
        additionalBenefitClaimRequested:
          type: boolean
          example: false
        faceAmount:
          type: number
          example: 25000
        premium:
          type: number
          example: 25000
        riderParticipants:
          type: array
          description: Maps from the UI Covered / Joint Covered Info fields. Each entry is
            a group of participants for the rider.
          items:
            type: array
            items:
              $ref: "#/components/schemas/ManageRiderParticipant"
        payoutDetails:
          $ref: "#/components/schemas/ManageRiderPayoutDetails"
        tableRatings:
          $ref: "#/components/schemas/ManageRiderTableRatings"
    ManageRiderParty:
      type: object
      description: A payee or owner party referenced for the rider's payout
        (self-serve; party already exists on the policy)
      properties:
        partyRole:
          $ref: "#/components/schemas/ManageRiderPartyRole"
        party:
          $ref: "#/components/schemas/ManageRiderPartyDetails"
    ManageRiderAction:
      type: string
      enum:
        - ADD
        - UPDATE
        - DELETE
        - NONE
      description: Action to perform for this rider entry
      example: UPDATE
    ManageRiderCategory:
      type: string
      enum:
        - BENEFIT
        - DISCOUNT
        - OTHER
        - RIDER
        - UNKNOWN
      description: Category of the rider
      example: RIDER
    ManageRiderType:
      type: string
      enum:
        - GLWB
        - GMWB
        - GMIB
        - GMAB
        - GMDB
        - RETURNOFPREMIUM
        - ENHANCEDDEATHBENEFIT
        - INCOMEACCELERATOR
        - NURSINGHOMEWAIVER
        - TERMINALILLNESS
        - WAIVEROFPREMIUM
        - ACCIDENTALDEATHBENEFIT
        - CHILDTERM
        - SPOUSETERM
        - TERMRIDER
        - GUARANTEEDINSURABILITY
        - ACCELERATEDDEATHBENEFIT
        - LONGTERMCARE
        - OVERLOANPROTECTION
        - PAIDUPADDITIONS
      description: Type of rider being managed
      example: GLWB
    ManageRiderOptedForPolicy:
      type: string
      enum:
        - YES
        - NO
      description: Whether the rider is opted for on the policy
      example: YES
    ManageRiderPayoutOption:
      type: string
      enum:
        - SINGLE
        - JOINT
      description: Maps from the UI Withdrawal Option field
      example: SINGLE
    ManageRiderParticipant:
      type: object
      description: A single rider participant (Covered / Joint Covered party)
      properties:
        partyRole:
          $ref: "#/components/schemas/ManageRiderParticipantPartyRole"
        party:
          $ref: "#/components/schemas/ManageRiderParticipantParty"
    ManageRiderPayoutDetails:
      type: object
      properties:
        paymentFrequency:
          $ref: "#/components/schemas/ManageRiderPaymentFrequency"
        paymentStartDate:
          type: string
          format: date
          example: 2026-07-31
          description: Maps from the UI Payment Start Date field
        amountBasis:
          $ref: "#/components/schemas/ManageRiderAmountBasis"
        specifiedAmount:
          type: number
          nullable: true
          example: null
        specifiedPercentage:
          type: number
          nullable: true
          example: null
        currencyCode:
          type: string
          example: USD
        excessWithdrawalConsent:
          type: boolean
          example: false
    ManageRiderTableRatings:
      type: object
      properties:
        tableRating:
          type: string
          example: TABLEA
        flatExtras:
          type: array
          items:
            $ref: "#/components/schemas/ManageRiderFlatExtra"
    ManageRiderPartyRole:
      type: string
      enum:
        - PAYEE
        - OWNER
      description: Maps from the UI Payee field
      example: PAYEE
    ManageRiderPartyDetails:
      type: object
      properties:
        partyId:
          type: string
          example: Party_PI_1
        partyPercentage:
          type: number
          example: 100
        paymentForm:
          $ref: "#/components/schemas/PaymentForm"
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/ManageRiderPartyAddress"
        bankDetails:
          type: array
          items:
            $ref: "#/components/schemas/ManageRiderPartyBankDetails"
    ManageRiderParticipantPartyRole:
      type: string
      enum:
        - JOINTINSURED
        - COVERAGEINSURED
      description: Role of the party participating in the rider
      example: COVERAGEINSURED
    ManageRiderParticipantParty:
      type: object
      description: Reference to an existing policy party by partyId (self-serve)
      properties:
        partyId:
          type: string
          example: Party_PI_1
    ManageRiderPaymentFrequency:
      type: string
      enum:
        - MONTHLY
        - QUARTERLY
        - BIANNUALLY
        - ANNUALLY
      description: Maps from the UI Payment Frequency field
      example: MONTHLY
    ManageRiderAmountBasis:
      type: string
      enum:
        - MAXIMUMANNUALBENEFIT
        - SPECIFIEDAMOUNT
        - SPECIFIEDPERCENTAGE
        - REQUIREDMINIMUMDISTRIBUTION
      description: Basis used to determine the payout amount
      example: MAXIMUMANNUALBENEFIT
    ManageRiderFlatExtra:
      type: object
      properties:
        type:
          type: string
          example: PERMANENT
        amount:
          type: number
          example: 250000
        duration:
          type: number
          example: 5
        durationType:
          $ref: "#/components/schemas/ManageRiderFlatExtraDurationType"
    PaymentForm:
      type: string
      enum:
        - DTCC
        - CREDITCARD
        - ACH
        - CHECK
        - WIRE
        - EXCHANGE
        - EFT
      description: Mode of payment
    ManageRiderPartyAddress:
      type: object
      description: Reference to an existing policy address by addressId (self-serve)
      properties:
        addressId:
          type: string
          example: Address_PI_1
    ManageRiderPartyBankDetails:
      type: object
      description: Reference to an existing policy bank record by bankId (self-serve)
      properties:
        bankId:
          type: string
          example: Bank_PI_1
    ManageRiderFlatExtraDurationType:
      type: string
      enum:
        - YEARS
      description: Unit for the flat extra duration
      example: YEARS
    ManageRiderRequest:
      type: object
      description: |
        Self-serve request body for manage rider eligibility, validation, and submit endpoints
        (POST `/bpm/v1/policies/{planCode}/{policyNumber}/managerider/eligibilitycheck`,
        `/managerider/validation`, and `/managerider`). Assumes all referenced parties and rider
        participants already exist on the policy, identified by partyId only.
      properties:
        correlationId:
          type: string
          description: The unique ID to track transaction request across all systems
          example: e3bdb22b-790f-4357-ae60-42cdb0ff0d12
        reverseInitiator:
          type: boolean
          description: Property to isolate source transaction(s) that initiated the reversal
          default: false
        externalIdentifiers:
          $ref: "#/components/schemas/ManageRiderExternalIdentifiers"
        transactionReason:
          $ref: "#/components/schemas/ManageRiderTransactionReason"
        riders:
          type: array
          description: Maps from the UI rider fields (Withdrawal Option, Exercise Date,
            Covered/Joint Covered Info, Payment Frequency, Payment Start Date)
          items:
            $ref: "#/components/schemas/ManageRiderRider"
        parties:
          type: array
          description: Maps from the UI Payee and Payment Method fields
          items:
            $ref: "#/components/schemas/ManageRiderParty"
      required:
        - riders
```