---
title: "AdhocAnnuitization"
url: "https://developers.zinnia.com/apis/policy-service-0-1-0/versions/8306e031-b41c-452a-a7ed-d73d65602086/schemas/AdhocAnnuitization"
---

> Full API specification: https://developers.zinnia.com/apis/policy-service-0-1-0/versions/8306e031-b41c-452a-a7ed-d73d65602086.md

# AdhocAnnuitization

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Policy Service
  version: 0.0.21
servers:
  - url: https://uat.api.zinnia.io
components:
  schemas:
    AdhocExternalIdentifiers:
      type: object
      properties:
        referenceNumber:
          type: string
          description: The unique payment reference number for all premium-related
        externalTransactionId:
          type: string
          description: The unique ID to identify transaction on carrier side
    TaxWithholdingInstructions:
      type: object
      properties:
        partyId:
          type: string
          description: A unique identifier linking the party to the policy
          example: Party_PI_1
        partyRole:
          type: string
          enum:
            - OWNER
            - PRIMARYBENEFICIARY
            - CONTINGENTBENEFICIARY
            - INSURED
            - PAYOR
            - PAYEE
            - AGENT
            - PRIMARYWRITINGAGENT
            - PRIMARYSERVICINGAGENT
            - ADDITIONALSERVICINGAGENT
            - ADDITIONALWRITINGAGENT
            - THIRDPARTYDESIGNEE
            - JOINTOWNER
            - COVERAGEINSURED
            - ASSIGNEE
            - ANNUITANT
            - EXCHANGECOMPANY
            - JOINTANNUITANT
            - GRANTOR
            - TRUSTEE
            - POWEROFATTORNEY
            - AUTHORIZEDSIGNATORY
            - OTHERINTERESTEDPARTY
            - CONTINGENTOWNER
            - THIRDPARTYADMINISTRATOR
            - CARRIER
            - SUCCESSORTRUSTEE
            - COVERAGEJOINTINSURED
          description: Roles that are essential in structuring life insurance and annuity
            contracts to meet the financial goals of policyholders and
            beneficiaries
        taxWithholdingType:
          $ref: "#/components/schemas/TaxWithholdingType"
        taxRateToUse:
          $ref: "#/components/schemas/TaxRateToUse"
        filingStatus:
          $ref: "#/components/schemas/FilingStatus"
        dollar:
          type: number
          description: The amount portion of the taxable transaction amount to be withheld
          example: 10
          format: double
        percentage:
          type: number
          description: The percentage of the taxable transaction amount to be withheld
          example: 50
          format: double
        exemptions:
          type: number
          description: The number of exemptions claimed for tax withholding within a tax
            year
          example: 0
          format: int32
        taxJurisdiction:
          type: string
          description: The legal tax authority (state or federal) governing the
            withholding process
          example: USA_WY
        contribution:
          type: string
          enum:
            - NOTAPPLICABLE
            - EMPLOYEEVOLUNTARY
            - EMPLOYEEDISCRETIONARY
          description: Not applicable, Employee Voluntary and Employee Discretionary
        taxFormType:
          type: string
          enum:
            - T1035COSTBASIS
            - T1035LOANTRANSFER
            - T1035SURRENDER
            - T1035TAXADVANTAGE
            - T1099R
            - TAXDISCLOSUREFORMW4P
            - TAXDISCLOSUREFORMW8
            - USW4TAXFORM
            - W9
            - VOIDCHECK
          description: The Tax Form Type refers to the specific IRS or government form
            used as the basis for determining an individual’s or entity’s tax
            withholding status on financial products such as life insurance
            policies, annuities, or investment accounts
        w4p:
          $ref: "#/components/schemas/W4P"
    AdhocDisbursementParty:
      type: object
      properties:
        partyRole:
          $ref: "#/components/schemas/PartyRole"
        partyId:
          type: string
          description: unique identifier linking the party to the policy
          example: Party_PI_1
        paymentForm:
          $ref: "#/components/schemas/PaymentForm"
        allocationPercentage:
          type: number
          description: The percentage of the total disbursement allocated to the payee
          example: 100
          format: double
        bankId:
          type: string
          description: A unique identifier for the financial institution handling the
            transaction
          example: Bank_1
        addressId:
          type: string
          description: A unique identifier for the address associated with the payee or
            policyholder
          example: "1"
        forBenefitOfOrForFurtherCredit:
          type: string
          description: FBO - For Benefit Of, FFC - For Further Credit. (To notate a second
            beneficiary or to designate a person or organization when funds are
            disbursed out)
          example: John Doe
        forBenefitOfOrForFurtherCreditIndicator:
          type: boolean
          example: true
          description: Indicates whether the outgoing funds are being requested for the
            benefit of or for further credit to another person or organization.
    Charge:
      type: object
      properties:
        chargeType:
          $ref: "#/components/schemas/TransactionChargeType"
        chargeWaiverIndicator:
          $ref: "#/components/schemas/ChargeWaiverIndicator"
        chargeWaiverReason:
          type: string
          description: The reason why a charge was waived (e.g., Promotional Waiver,
            Policy Exception)
          example: "100"
        partyId:
          type: string
          description: The partyId to which the charge is applied.
          example: Party_PI_1
    AnnuitizationFeature:
      type: object
      properties:
        frequency:
          $ref: "#/components/schemas/Frequency"
        firstPaymentDate:
          type: string
          format: date
          example: 2023-01-01
          description: Date (with pattern "yyyy-mm-dd") when the transaction was
            originally scheduled or expected to happen, can be a non-business
            day
        paymentForm:
          $ref: "#/components/schemas/PaymentForm"
        distributionCode:
          $ref: "#/components/schemas/DistributionCode"
        accountNumber:
          type: string
          example: "123456789"
          description: The account number for the annuitization feature
        participantId:
          type: string
          example: "123456789"
          description: The participant ID for the annuitization feature
    Suppression:
      type: object
      properties:
        suppressionType:
          $ref: "#/components/schemas/SuppressionType"
        suppressionReason:
          type: string
          description: Specifies the specific reason or justification for applying the
            suppression. It explains why the suppression was applied.
    TaxWithholdingType:
      type: string
      enum:
        - FEDERAL
        - STATE
        - NRA
        - BACKUP
    TaxRateToUse:
      type: string
      enum:
        - NOWITHHOLDINGELECTED
        - USEVALUESENTERED
        - NOWITHHOLDINGALLOWED
        - USEDEFAULTTABLE
        - ADDITIONALWITHHOLDING
        - TAKEINPUTTEDVALUE
    FilingStatus:
      type: string
      enum:
        - SINGLE
        - DOMESTICPARTNERSHIP
        - DEFAULT
        - MARRIED
        - HEADOFHOUSEHOLD
        - WIDOWED
        - DIVORCED
        - MARRIEDFILINGSEPARATELY
    W4P:
      type: object
      properties:
        totalAmountOfOtherIncomeAndOtherPensionsOrAnnuities:
          type: number
          format: double
          example: 12.12
          description: "Below Amounts are for periodic Payments Only  - Certain States
            Require these amounts to be entered "
        totalAmountOfClaimsAndOtherCredits:
          type: number
          format: double
          example: 213.73
          description: "This indicates the total amount of tax claims and credits party is
            eligible for to reduce the tax liabilities "
        otherIncome:
          type: number
          format: double
          example: 144.53
          description: "Not from Jobs or Pension/Annuities "
        otherDeduction:
          type: number
          format: double
          example: 42.83
          description: If Standard Deduction is not used
    PartyRole:
      type: string
      enum:
        - OWNER
        - PRIMARYBENEFICIARY
        - CONTINGENTBENEFICIARY
        - INSURED
        - PAYOR
        - PAYEE
        - AGENT
        - PRIMARYWRITINGAGENT
        - PRIMARYSERVICINGAGENT
        - ADDITIONALSERVICINGAGENT
        - ADDITIONALWRITINGAGENT
        - THIRDPARTYDESIGNEE
        - JOINTOWNER
        - COVERAGEINSURED
        - ASSIGNEE
        - ANNUITANT
        - EXCHANGECOMPANY
        - JOINTANNUITANT
        - GRANTOR
        - TRUSTEE
        - POWEROFATTORNEY
        - AUTHORIZEDSIGNATORY
        - OTHERINTERESTEDPARTY
        - CONTINGENTOWNER
        - THIRDPARTYADMINISTRATOR
        - CARRIER
        - SUCCESSORTRUSTEE
        - COVERAGEJOINTINSURED
    PaymentForm:
      type: string
      enum:
        - DTCC
        - CREDITCARD
        - ACH
        - CHECK
        - WIRE
        - EXCHANGE
        - PREMIUMLOAN
    TransactionChargeType:
      type: string
      enum:
        - COSTOFINSURANCE
        - EXPENSECHARGE
        - UNITEXPENSECHARGE
        - RIDERCHARGE
        - SURRENDERCHARGE
        - WITHDRAWALCHARGE
        - PAYMENTCHARGE
        - COVERAGECHARGE
        - COVERAGECREDIT
        - PREMIUMTAX
        - MARKETVALUEADJUSTMENT
        - BONUSRECAPTURE
        - EQUITYINDEXADJUSTMENT
        - PRODUCTLIMITS
        - DEATHBENEFITINTEREST
        - FUTURECHARGESFORTRANSACTION
        - REDEMPTIONFEE
        - MAILCHARGE
        - FUNDFEE
        - INEFFECT
        - ALL
        - OVERNIGHTMAIL
        - WIRE
    ChargeWaiverIndicator:
      type: string
      enum:
        - Yes
        - No
    Frequency:
      type: string
      enum:
        - DAILY
        - EVERYTWOWEEKS
        - MONTHLY
        - SEMIANNUAL
        - QUARTERLY
        - ANNUAL
        - SINGLEPAYMENT
    DistributionCode:
      type: string
      enum:
        - DEFAULT
        - PREMATUREDISTRIBUTION
        - EXCEPTIONAPPLIES
        - DISABILITY
        - DEATH
        - DEATHEXCLUSION
        - DEATHROLLOVER
        - EXCHANGE1035
        - NORMALDISTRIBUTION
        - COSTOFCURRENTLIFEINSURANCEPROTECTION
        - QUALIFIEDROLLOVER
        - ROTHDISTRIBUTIONNOEXCEPTION
        - QUALIFIEDLOANDISTRIBUTION
        - PREMATURELOANDISTRIBUTION
        - QUALIFIEDROTHINDIVIDUALRETIREMENTARRANGEMENTDISTRIBUTION
        - ROTHINDIVIDUALRETIREMENTACCOUNTSDISTRIBUTIONEXCEPTIONAPPLIES
        - EXCESSCONTRIBUTIONSPLUSEARNINGSEXCESSDEFERRALSTAXABLEIN2009
        - NONTAXABLEEVENT
        - GROSSPAIDTOATTORNEY
        - OTHERINCOME
        - NONEMPLOYEECOMPENSATION
        - PREMATUREEXCEPTION
        - ROYALTIES
        - DEATHTRANSFER4H
        - PROHIBITEDTRANSACTION
        - TENYEARTAXOPTION
        - TRUSTEETOTRUSTEETRANSFER
        - QUALIFIEDDOMESTICRELATIONSORDERLIKETOLIKENO1099
        - DISTRIBUTIONSUNDEREMPLOYEEPLANSCOMPLIANCERESOLUTIONSYSTEM
        - CHARITABLEGIFT
        - LOANSASDISTRIBUTIONS
        - QUALIFIEDPLANLOANOFFSET
        - RECHARACTERIZEDINDIVIDUALRETIREMENTARRANGEMENTCURRENTYEAR
        - EXCESSCONTRIBUTION1YEARPRIORTAX
        - RECHARACTERIZEDINDIVIDUALRETIREMENTACCOUNTSPREVIOUSYEAR
        - EARLYDISTRIBUTIONFROMSAVINGSINCENTIVEMATCHPLANFOREMPLOYEES
        - DIRECTTRANSFER
        - EXCESSCONTRIBUTIONSPLUSEARNINGSEXCESSDEFERRALSANDOREARNINGSTAXABLEIN2024
        - EXCESSCONTRIBUTIONS2YEARPRIORTAX
        - DIRECTROLLOVERQUALPLANTAXSHELTEREDANNUITY
        - SEPARATIONFROMSERVICE
        - INDIVIDUALRETIREMENTARRANGEMENTTOROTHINDIVIDUALRETIREMENTARRANGEMENT
        - QUALIFIEDDOMESTICRELATIONSORDERROLLOVERTOINDIVIDUALRETIREMENTARRANGEMENT2G
        - QUALIFIEDDOMESTICRELATIONSORDERPAYMENTTOSPOUSE
        - FIRSTTIMEHOMEBUYERINDIVIDUALRETIREMENTARRANGEMENTONLY
        - EDUCATIONEXPENSE
        - MEDICALEXPENSE
        - FEEADMIN
        - FEEASSET
        - FEECONTRIBUTION
        - FEELUMPSUMDEATH
        - FEELUMPSUMDISABILITY
        - FEELUMPSUMPURCHASEDANNUITY
        - FEELUMPSUMOTHER
        - FEENEWRETIREEWITHPERPAYMENT
        - FEEEXISTINGRETIREMENTINFORCE
        - FEECONTRACT
        - FEEEXISTINGRETIREMENTINCREASE
        - FEETHIRDPARTY
        - LUMPSUMDEATH
        - LUMPSUMDISABILITY
        - LUMPSUMPURCHASEDANNUITY
        - LUMPSUMOTHER
        - FEEINTERNATIONALPROGRAMSGROUPEXPENSE
        - FROMFUND
        - RELEASERESERVE
        - HEALTHDEDUCTION
        - FEEMARKETVALUE
        - FEEANNUITYADMINISTRATION
        - SECTION1035EXCHANGEPARTIAL
        - QUALIFIEDDOMESTICRELATIONSORDERNORMALDISTRIBUTION
        - QUALIFIEDDOMESTICRELATIONSORDERSECTION1035
        - FEELONGTERMCAREINSURANCE
        - DESIGNATEDROTHACCOUNTDISTRIBUTION
        - REPORTABLEDEATHBENEFITSUNDERSECTION6050Y
        - DISTRIBUTIONOFTRADITIONALINDIVIDUALRETIREMENTARRANGEMENTASSETSNOTHAVINGAREADILYAVAILABLEFAIRMARKETVALUE
        - DIVIDENDSDISTRIBUTEDFROMANEMPLOYEESTOCKOWNERSHIPPLANSUNDERSECTION404K
        - DIRECTROLLOVEROFADESIGNATEDROTHACCOUNT
        - DEATHQUALIFIEDCHARITABLEDISTRIBUTION
        - NORMALQUALIFIEDCHARITABLEDISTRIBUTION
    SuppressionType:
      type: string
      description: Specifies the category or type of suppression being applied to a
        transaction. It indicates what kind of suppression is in effect.
      enum:
        - CORRESPONDENCE
        - TAX
        - DISBURSEMENT
        - COMMISSION
    AdhocAnnuitization:
      type: object
      properties:
        correlationId:
          type: string
          example: 864e43a0-2c2f-4a11-9d7f-69ed40115066
          description: The unique ID to track transaction request across all systems
        effectiveDate:
          type: string
          format: date
          example: 2023-01-01
          description: Date (with pattern "yyyy-mm-dd") when the transaction was
            originally scheduled or expected to happen, can be a non-business
            day
        reverseInitiator:
          type: boolean
          description: >-
            A boolean flag that applies only to financial transactions. 
             When set to true, it allows a backdated transaction to be processed.  
            This triggers a reversal on the policy to the earliest transaction
            on the specified effective date, 

            applies the new transaction, and then reprocesses all subsequent
            transactions (similar to (R&R) process). 

            This ensures that the policy`s financial history remains accurate
            and aligned with the backdated change.
        externalIdentifiers:
          $ref: "#/components/schemas/AdhocExternalIdentifiers"
        taxWithholdingInstructions:
          $ref: "#/components/schemas/TaxWithholdingInstructions"
        parties:
          $ref: "#/components/schemas/AdhocDisbursementParty"
        charges:
          type: array
          items:
            $ref: "#/components/schemas/Charge"
        annuitizationFeature:
          $ref: "#/components/schemas/AnnuitizationFeature"
        suppression:
          type: array
          items:
            $ref: "#/components/schemas/Suppression"
```