--- title: "Submit Manage Rider Transaction" url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/operations/submitManageRider1" --- > Full API specification: https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84.md # Submit Manage Rider Transaction `POST` `/policy/v1/transactions/{planCode}/{policyNumber}/managerider` Operation ID: `submitManageRider1` ## Path parameters - `planCode` (string, required) - `policyNumber` (string, required) ## Request body (required) Content types: `application/json` ## Responses - `202` - Submit Transaction Successful - `400` - Rules and Transaction Failure - `500` - Unexpected error occured, please check server logs ## 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 paths: /policy/v1/transactions/{planCode}/{policyNumber}/managerider: post: x-kong-plugin-pre-function: config: access: - > local path = kong.request.get_path() local new_path = path:gsub("^/policy/v1/transactions", "/bpm/v1/policies") kong.service.request.set_path(new_path) tags: - Financial Transactions summary: Submit Manage Rider Transaction operationId: submitManageRider1 parameters: - name: planCode in: path required: true schema: type: string - name: policyNumber in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ManageRiderRequest" responses: "202": description: Submit Transaction Successful content: application/json: schema: $ref: "#/components/schemas/TransactionAcceptedResponse" "400": description: Rules and Transaction Failure content: application/json: schema: $ref: "#/components/schemas/TransactionResponse" examples: failure: $ref: "#/components/examples/failureTransactionResponse" "500": description: Unexpected error occured, please check server logs security: - Auth0: [] security: - Auth0: [] components: schemas: 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 TransactionAcceptedResponse: type: object properties: correlationId: type: string example: 3a2a3435-2089-4b81-9959-e0d569ccf4f0 description: Unique identifier which used by every system to trace the request caseId: type: string example: CA0000369469 description: Zinnia Live Case ID caseStatus: type: string example: IN_PROGRESS description: Zinnia Live Case Status pdfId: type: string description: 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 TransactionResponse: type: object properties: status: type: string enum: - success - failure error: type: array items: $ref: "#/components/schemas/Error" quoteResponse: type: object 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" Error: type: object properties: errorCode: type: string example: BPM.NM.002 description: This is the NIGO id generated by BPM system attribute: type: string error: type: string description: This is the error generated by BPM system resolution: type: string description: Resolution generated by BPM system to resolve the error 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 examples: failureTransactionResponse: value: status: failure validationResult: - errorCode: BPM.NM.005 attribute: null error: Amount request is invalid. resolution: Please check the One Time Premium Amount and submit the request again. - errorCode: BPM.NM.003 attribute: null error: Party information does not match with information in the Zahara system. resolution: Please validate the party information and submit the request again. securitySchemes: Auth0: type: openIdConnect openIdConnectUrl: https://login.dev.zinnia.com/.well-known/openid-configuration x-kong-security-openid-connect: config: run_on_preflight: true scopes_claim: - https://dev.api.zinnia.io/permissions audience_claim: - aud audience_required: - https://dev.api.zinnia.io client_id: - client_id auth_methods: - bearer enabled: true protocols: - grpc - grpcs - http - https ```