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

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

# IriPolicyTransactions

## OpenAPI definition

```yaml
openapi: 3.0.0
info:
  title: Policy Service
  version: 0.0.21
servers:
  - url: https://uat.api.zinnia.io
components:
  schemas:
    IriPolicyTransaction:
      type: object
      properties:
        transactionId:
          type: string
          description: Unique identifier assigned to the transaction.
          pattern: ^[A-Za-z0-9._-]{1,100}$
          example: TX-1001
        originalTransactionId:
          type: string
          description: The unique identifier of the reversed transaction. When a
            transaction is reversed, this field holds the ID of the original
            transaction that was reversed. We capture this to ensure proper
            tracking and auditing of financial adjustments within the system
          pattern: ^[A-Za-z0-9._-]{1,100}$
          example: TX-REF-0000
        partyPolicyChangeReferenceId:
          type: string
          description: Unique identifier for the impacted party data being updated with a
            transaction or event. For example, if multiple addresses are
            modified, this field identifies the specific address Id for which
            change is being processed
          pattern: ^[A-Za-z0-9._-]{1,100}$
          example: PAR-686
        partyPolicyNewReferenceId:
          type: string
          description: Trigger to Pass in API which non financial was newly added out of
            multiple change requests, for example a new email was added
          pattern: ^[A-Za-z0-9._-]{1,100}$
          example: PAR-908
        planCode:
          type: string
          description: The Plan Code is a carrier-assigned unique identifier used to
            distinguish a specific product, rate structure, and version of a
            life insurance or annuity policy. It ensures accurate policy
            tracking, pricing, and administration
          pattern: ^[A-Za-z0-9._-]{1,50}$
          example: FIAPRM01
        parentId:
          type: string
          description: The unique identifier of a Parent Transaction or Parent Program ID.
            The value of parentId varies based on the transaction type. >>For
            Subsequent Premium, One-Time Premium, Loan Repayment (One-Time &
            Systematic) → The Parent Payment Transaction ID is stamped. >> For
            Forceout and Disbursement → The Parent Money Out or Money In
            Transaction ID is stamped
          pattern: ^[A-Za-z0-9._-]{1,100}$
          example: ROOT-1
        transactionType:
          $ref: "#/components/schemas/IriTransactionType"
        requestDate:
          type: string
          description: The date when the transaction request was initiated or received in
            the system. For example, for system generated events date on which
            transaction was initiated by the system for adhoc events date on
            which transaction was received by the system.
          example: 2026-03-06
          format: date
        effectiveDate:
          type: string
          description: Represents the date on which the policy or contract became active
            and coverage officially began.
          example: 2026-03-06
          format: date
        processDate:
          type: string
          description: Represents the date when the transaction is processed by the system.
          example: 2026-03-06
          format: date
        reversalDate:
          type: string
          description: The date when a transaction is reversed in the system
          example: 9999-12-31
          format: date
        status:
          $ref: "#/components/schemas/IriTransactionStatus"
        transactionReason:
          $ref: "#/components/schemas/IriTransactionReason"
        transactionAmounts:
          description: Details of financial amounts associated with the transaction
          allOf:
            - $ref: "#/components/schemas/IriTransactionAmounts"
        charges:
          description: Charges applied as part of the transaction.
          type: array
          items:
            $ref: "#/components/schemas/IriTransactionCharge"
        taxWithholdingInstructions:
          description: Tax withholding instructions associated with the transaction.
          type: array
          items:
            $ref: "#/components/schemas/IriPartyTaxWithholdingInstruction"
        timestamp:
          type: string
          description: Create or update timestamp of the transaction event.
          example: 2026-03-06T12:00:00Z
          format: date-time
        isReverseInitiated:
          type: boolean
          description: Whether the transaction was initiated as a reversal
            (reverse-and-reprocess).
          example: false
        version:
          type: integer
          description: Version number of the policy after the transaction.
          example: 1
          format: int32
        externalIdentifiers:
          description: External identifiers associated with the transaction.
          allOf:
            - $ref: "#/components/schemas/IriTransactionExternalIdentifiers"
      required:
        - transactionId
        - planCode
        - requestDate
        - effectiveDate
        - processDate
        - status
        - transactionReason
        - timestamp
        - version
    IriTransactionType:
      type: string
      description: Specifies the type of transaction being performed, such as Premium
        Payment, Loan Repayment, Anniversary etc
      enum:
        - SubsequentPayment
        - OneTimePremium
        - PartialWithdrawalOneTime
        - SystematicPartialWithdrawal
        - RequiredMinimumDistributionOneTime
        - SystematicRequiredMinimumDistribution
        - FullSurrender
        - FundTransfer
        - FundAllocationsChange
        - Sweep
        - DollarCostAverage
        - NewLoan
        - LoanRepaymentOneTime
        - SystematicLoanRepayment
        - Annuitization
        - SystematicAnnuityPayout
        - PayoutAmountChange
        - ServiceCharge
        - RiderCharge
        - ValueAdjustment
        - InterestCredit
        - AddressChange
        - EmailChange
        - PhoneNumberChange
        - BeneficiaryChange
        - OwnerChange
        - BankAccountChange
        - CommunicationPreferenceChange
        - Reinstatement
        - Lapse
        - Other
    IriTransactionStatus:
      type: string
      description: 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
      enum:
        - Pending
        - Completed
        - Failed
        - Reversed
        - Canceled
        - PendingReversal
    IriTransactionReason:
      type: string
      description: The justification or business reason for the transaction
      enum:
        - ONETIMEPREMIUM
        - GRACEPERIODPREMIUM
        - REINSTATEMENTPREMIUM
        - EXCHANGE1035
        - SURRENDER
        - AMOUNTEXCESSTOMEC
        - AMOUNTEXCESSTOGUIDELINE
        - CURRENTVALUE
        - COSTBASIS
        - GUIDELINESINGLEPREMIUM
        - GUIDELINELEVELPREMIUM
        - SEVENPAYPREMIUM
        - TOTALYTDPREMIUMAMOUNT
        - FACEDECREASECOVERAGE
        - INITIALPREMIUMEXPIRATION
        - COMPLIANCE
        - STARTINGPRICE
        - LUMPSUM
        - FIVEYEARDEFERRAL
        - SPOUSALCONTINUATION
        - DISCOUNT
        - CONTROLBUSINESSINDICATOR
        - NATIONALCHANGEOFADDRESS
    IriTransactionAmounts:
      type: object
      properties:
        requestedAmount:
          type: number
          description: Required when amountType is AMOUNT. Must not be provided for
            PERCENTAGE, MAX, FREEWITHDRAWALAMOUNT, WITHDRAWALUNTILBASIS, or
            EARNINGSONLY.
          example: 137547.78
          minimum: 0
          maximum: 9999999999.99
        requestedPercentage:
          type: number
          description: Required when amountType is PERCENTAGE. Must not be provided for
            AMOUNT, MAX, FREEWITHDRAWALAMOUNT, WITHDRAWALUNTILBASIS, or
            EARNINGSONLY.
          example: 10
          minimum: 0
          maximum: 100
        amountType:
          $ref: "#/components/schemas/IriTransactionAmountType"
        disbursementType:
          $ref: "#/components/schemas/IriDisbursementType"
        disbursementPaymentForm:
          $ref: "#/components/schemas/IriDisbursementPaymentForm"
    IriTransactionCharge:
      type: object
      properties:
        chargeType:
          $ref: "#/components/schemas/IriTransactionChargeType"
        isChargeWaived:
          type: boolean
          description: Whether the charge was waived.
          example: false
        chargeWaiverReason:
          type: string
          description: Reason the charge was waived.
          example: WITHIN_FREE_WITHDRAWAL
        chargeAmount:
          type: number
          description: Charge amount applied for this transaction.
          example: 374.75
          minimum: 0
          maximum: 9999999999.99
        chargeAppliedRate:
          type: number
          description: Rate (%) used to calculate the charge.
          example: 0.27
          minimum: 0
          maximum: 9999999999.99
    IriPartyTaxWithholdingInstruction:
      type: object
      properties:
        party:
          description: Impacted party details for withholding.
          allOf:
            - $ref: "#/components/schemas/IriPartyTaxWithholdingParty"
        taxWithholdingType:
          $ref: "#/components/schemas/IriTaxWithholdingType"
        taxRateToUse:
          $ref: "#/components/schemas/IriTaxRateToUse"
        filingStatus:
          $ref: "#/components/schemas/IriFilingStatus"
        dollar:
          type: number
          description: Fixed dollar amount to withhold. Mutually exclusive with percentage.
          example: 125
          minimum: 0
          maximum: 9999999999.99
        percentage:
          type: number
          description: Percentage rate to withhold. Mutually exclusive with dollar.
          example: 10
          minimum: 0
          maximum: 100
        exemptions:
          type: number
          description: Requested exemptions value.
          example: 0
          minimum: 0
          maximum: 99
        taxJurisdiction:
          type: string
          description: Jurisdiction for tax purposes. Required by the IRI schema when
            taxWithholdingType is STATE.
          example: NC
          maxLength: 50
      required:
        - taxWithholdingType
        - taxRateToUse
    IriTransactionExternalIdentifiers:
      type: object
      properties:
        referenceNumber:
          type: string
          description: Carrier payment reference number.
          example: EXT-REF-1001
          pattern: ^[A-Za-z0-9._-]{1,100}$
        externalTransactionId:
          type: string
          description: Carrier-side transaction identifier.
          example: EXT-TX-1001
          pattern: ^[A-Za-z0-9._-]{1,100}$
        externalArrangementId:
          type: string
          description: Carrier-side systematic program (arrangement) identifier.
          example: ARR-001
          pattern: ^[A-Za-z0-9._-]{1,100}$
    IriTransactionAmountType:
      type: string
      description: Indicates how the scheduled amount is defined for the systematic
        program, such as a fixed amount, percentage, maximum available amount,
        free withdrawal amount, withdrawal until basis, earnings only, pro rata
        amount, or modified earnings only.
      enum:
        - AMOUNT
        - PERCENTAGE
        - MAX
        - FREEWITHDRAWALAMOUNT
        - WITHDRAWALUNTILBASIS
        - EARNINGSONLY
    IriDisbursementType:
      type: string
      description: Type of amount for withdrawal such as Gross or Net.
      enum:
        - GROSS
        - NET
    IriDisbursementPaymentForm:
      type: string
      description: Transaction disbursement payment form. Uses the recurring
        disbursement vocabulary with EFT; EXCHANGE is intentionally excluded
        because it applies only to party-level exchange servicing.
      enum:
        - DTCC
        - EFT
        - ACH
        - CHECK
        - WIRE
    IriTransactionChargeType:
      type: string
      description: Type of charge applied to the transaction.
      enum:
        - SERVICE_CHARGE
        - RIDER_CHARGE
        - ADMINISTRATIVE_CHARGE
        - SURRENDER_CHARGE
        - MVA
        - TAX
        - COST_OF_INSURANCE
        - EXPENSE_CHARGE
        - UNIT_EXPENSE_CHARGE
        - WITHDRAWAL_CHARGE
        - OTHER
    IriPartyTaxWithholdingParty:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/IriPartyType"
        firstName:
          type: string
          description: First name of the individual party.
          example: John
          minLength: 1
          maxLength: 100
        middleName:
          type: string
          description: Middle name of the individual party.
          example: Q
          minLength: 1
          maxLength: 100
        lastName:
          type: string
          description: Last name of the individual party.
          example: Public
          minLength: 1
          maxLength: 100
        name:
          type: string
          description: Entity name of the party.
          example: Public Family Trust
          minLength: 1
          maxLength: 100
        taxId:
          type: string
          description: Tax identification number for the party.
          example: "123456789"
          minLength: 9
          maxLength: 9
          pattern: ^[0-9]{9}$
      required:
        - type
        - taxId
    IriTaxWithholdingType:
      type: string
      description: Type of tax withholding.
      enum:
        - FEDERAL
        - STATE
        - NRA
        - BACKUP
    IriTaxRateToUse:
      type: string
      description: Selected tax rate source.
      enum:
        - NOWITHHOLDINGELECTED
        - USEVALUESENTERED
        - NOWITHHOLDINGALLOWED
        - USEDEFAULTTABLE
    IriFilingStatus:
      type: string
      description: Tax filing status. Usually populated when default withholding
        tables are used.
      enum:
        - SINGLE
        - DOMESTICPARTNERSHIP
        - DEFAULT
        - MARRIED
        - HEADOFHOUSEHOLD
        - WIDOWED
        - DIVORCED
    IriPartyType:
      type: string
      description: Type of party.
      enum:
        - individual
        - entity
    IriPolicyTransactions:
      type: object
      properties:
        startIndex:
          type: number
          description: Used for pagination to indicate where the returned page starts
            within the full result set.
          example: 0
          minimum: 0
        itemsCount:
          type: number
          description: Number of records included in the current response page.
          example: 1
          minimum: 0
        totalItemsCount:
          type: number
          description: Total number of records available that match the request criteria,
            independent of pagination.
          example: 1
          minimum: 0
        transactions:
          description: Transactions associated with the policy.
          type: array
          items:
            $ref: "#/components/schemas/IriPolicyTransaction"
      required:
        - startIndex
        - itemsCount
        - totalItemsCount
        - transactions
```