---
title: "Submit Payee Role Change"
url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/operations/partyRoleChangePayee1"
---

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

# Submit Payee Role Change

`POST` `/policy/v1/transactions/{planCode}/{policyNumber}/parties/payee`

Operation ID: `partyRoleChangePayee1`

Submits the Payee role change transaction for processing. Generic Party Role Change endpoint, shared across all multi-party-update transactions (Payee, Trustee, Power of Attorney, Owner, Joint Owner, Authorized Signatory, Coverage Joint Insured, and future party roles using the same MultiPartyRoleChangeRequest/PartyUpdate request format).

## Path parameters

- `planCode` (string, required) - Plan Code
- `policyNumber` (string, required) - Policy Number

## Request body (required)

Content types: `application/json`

## Responses

- `202` - Submit Transaction Successful
- `500` - Internal server error. Please check server logs for more details.

## 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}/parties/payee:
    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:
        - Non Financial Transactions
      summary: Submit Payee Role Change
      description: >
        Submits the Payee role change transaction for processing.

        Generic Party Role Change endpoint, shared across all multi-party-update
        transactions (Payee, Trustee, Power of Attorney, Owner, Joint Owner,
        Authorized Signatory, Coverage Joint Insured, and future party roles
        using the same MultiPartyRoleChangeRequest/PartyUpdate request format).
      operationId: partyRoleChangePayee1
      parameters:
        - name: planCode
          in: path
          required: true
          schema:
            type: string
          description: Plan Code
        - name: policyNumber
          in: path
          required: true
          schema:
            type: string
          description: Policy Number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MultiPartyRoleChangeRequest"
            examples:
              PayeeRoleChangeSubmitExample:
                summary: Payee role change submit request example
                value:
                  correlationId: e3bdb22b-790f-4357-ae60-42cdb0ff0d12
                  planCode: EVGFIA909
                  policyNumber: EVFIA095509100
                  effectiveDate: 2026-07-24
                  requestSource: DATA_ENTRY
                  partyUpdates:
                    - action: ADD
                      partyRole: PAYEE
                      party:
                        firstName: John
                        lastName: Doe
                        dateOfBirth: 1980-05-12
                        gender: M
      responses:
        "202":
          description: Submit Transaction Successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionAcceptedResponse"
        "500":
          description: Internal server error. Please check server logs for more details.
      security:
        - Auth0: []
security:
  - Auth0: []
components:
  schemas:
    MultiPartyRoleChangeRequest:
      type: object
      description: >
        Generic request body for a party role change transaction
        (pa-bpm-txn-common

        MultiPartyRoleChangeRequest), shared across all multi-party-update

        transactions (Payee, Trustee, Power of Attorney, Owner/Joint Owner,

        Authorized Signatory, Coverage Joint Insured, and future party roles).

        Each party role is exposed at its own dedicated path (see the

        .../parties/{role}/... operations); this schema is the shared contract

        across all of them.
      properties:
        planCode:
          type: string
          description: Plan code (may duplicate path parameter)
        policyNumber:
          type: string
          description: Policy number (may duplicate path parameter)
        caseId:
          type: string
          example: CA0000007389
          description: Zinnia Live Case ID
        correlationId:
          type: string
          description: The unique ID to track transaction request across all systems
          example: e3bdb22b-790f-4357-ae60-42cdb0ff0d12
        carrierId:
          type: string
          example: FNWL
          description: Carrier identifier
        effectiveDate:
          type: string
          format: date
          example: 2026-07-24
          description: Effective date for the party role change
        requestSource:
          type: string
          enum:
            - DATA_ENTRY
            - SELF_SERVE
          description: Origin of the request
        partyUpdates:
          type: array
          minItems: 1
          description: One or more party changes (ADD, UPDATE, or DELETE) to apply
          items:
            $ref: "#/components/schemas/PartyUpdate"
        signatures:
          type: array
          description: Signatures associated with the party role change
          items:
            $ref: "#/components/schemas/SignatureDto"
        documents:
          type: array
          description: Supporting documents for the party role change
          items:
            $ref: "#/components/schemas/PartyRoleChangeDocument"
        selfServeFlow:
          type: boolean
          description: Whether the request originated from a self-serve flow
          example: true
        supportingDocumentAttached:
          type: boolean
          description: Indicates whether supporting documents are attached
          example: true
        changeReason:
          type: string
          description: Reason for the change
      required:
        - effectiveDate
        - partyUpdates
    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
    PartyUpdate:
      type: object
      description: >
        A single party change entry (pa-bpm-txn-common PartyUpdateDto). One

        MultiPartyRoleChangeRequest carries a list of these - one per party
        being

        added, updated, or removed in this transaction.
      properties:
        action:
          $ref: "#/components/schemas/PartyUpdateAction"
        customerId:
          type: string
          description: Top-level customer ID. Sent alongside party.customerId for the same
            party.
        relationshipToParty:
          type: string
        partyRole:
          type: string
          description: >
            The specific party role for this entry. Each backing microservice
            sends

            its own literal value today, with no shared casing convention across

            services (tracked for future normalization): PAYEE (payee-change),

            TRUSTEE (trustee-change), ATTORNEY_IN_FACT (poa-change),

            AuthorizedSignatory (authorized-signatory-change), Owner /
            JointOwner

            (owner-mgmt), CoverageJointInsured (rider-role-change).
          example: CoverageJointInsured
        referencePartyId:
          type: string
          description: >
            PartyId of an existing party on the policy to clone when adding a
            new

            party (e.g. ADD a new Coverage Joint Insured with the same details
            as

            an existing party). Only relevant for action ADD; not forwarded to

            downstream carrier systems.
        partyStatus:
          type: string
        carrierDecision:
          type: string
        rejectionReason:
          type: string
        delegatedExecutionAuthorityType:
          type: string
          description: Power of Attorney specific - delegated execution authority type
        powerOfAttorneyAccessLevelType:
          type: string
          description: Power of Attorney specific - access level type
        party:
          $ref: "#/components/schemas/PartyDetailsForPartyRole"
      required:
        - action
    SignatureDto:
      type: object
      description: Signature details for the agent change
      properties:
        signType:
          type: string
          description: Type of the signature (e.g., digital, physical)
          example: DIGITAL
        isSignedPresent:
          type: boolean
          description: Indicates if a signature is present
          example: true
        signDate:
          type: string
          format: date
          description: Date when the signature was applied
          example: 2024-01-01
        signPrintName:
          type: string
          description: Name of the person signing
          example: John Doe
        signGuarantee:
          type: string
          description: Guarantee associated with the signature
          example: FULL
        signDesignation:
          type: string
          description: Designation of the signer
          example: MANAGER
    PartyRoleChangeDocument:
      type: object
      description: Supporting document reference for a party role change
      properties:
        documentId:
          type: string
          example: DOC123456
        documentType:
          type: string
          example: NFO_FORM
        documentDate:
          type: string
          format: date
          example: 2026-06-26
        caseId:
          type: string
          example: CA0000007389
        policyNumber:
          type: string
          example: WL987654321
        planCode:
          type: string
          example: WL1001
    PartyUpdateAction:
      type: string
      description: Action to apply for this party update entry
      enum:
        - ADD
        - UPDATE
        - DELETE
        - NONE
      example: ADD
    PartyDetailsForPartyRole:
      type: object
      description: >
        Full party detail payload (pa-bpm-txn-common
        PartyDetailsForPartyRoleDto).

        Only the fields relevant to the action/party role need to be populated.
      properties:
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        timestamp:
          type: string
        customerId:
          type: string
        partyId:
          type: string
          description: |
            Party identifier. Required for UPDATE/DELETE actions; omit (or leave
            null) for ADD so the carrier assigns one. Defaults to a random UUID
            client-side if not explicitly set - always set explicitly for
            UPDATE/DELETE.
        parentPartyId:
          type: string
          description: Parent party identifier (e.g. for a minor's guardian relationship)
        partyType:
          type: string
        partyStatus:
          type: string
        beneficiaryPercentage:
          type: integer
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        fullName:
          type: string
        prefix:
          type: string
        suffix:
          type: string
        gender:
          type: string
        genderIdentity:
          type: string
        dateOfBirth:
          type: string
          format: date
        attainedAge:
          type: integer
        birthCountry:
          type: string
        citizenCountry:
          type: string
        birthState:
          type: string
        doingBusinessAs:
          type: string
        abbreviatedName:
          type: string
        organizationCode:
          type: string
        entityType:
          type: string
        trustDate:
          type: string
          format: date
        trustType:
          type: string
        trustTitle:
          type: string
        trustAccessCode:
          type: string
        amendedTrustDate:
          type: string
          format: date
        governingStateOfTrust:
          type: string
        preferredCommunicationType:
          type: string
        preferredAddressIndicator:
          type: string
        identifications:
          type: array
          items:
            $ref: "#/components/schemas/PartyRoleChangeIdentification"
        addresses:
          type: array
          items:
            $ref: "#/components/schemas/PartyRoleChangeAddress"
        phones:
          type: array
          items:
            $ref: "#/components/schemas/PartyRoleChangePhone"
        emails:
          type: array
          items:
            $ref: "#/components/schemas/PartyRoleChangeEmail"
        bankDetails:
          type: array
          items:
            $ref: "#/components/schemas/PartyRoleChangeBankDetails"
        version:
          type: string
        agentExternalId:
          type: string
        agentType:
          type: string
        agentPercentage:
          type: number
          format: double
        partyPercentage:
          type: number
          format: double
        collateralAmount:
          type: number
          format: double
        deathDetails:
          $ref: "#/components/schemas/PartyRoleChangeDeathDetails"
        impairmentDetails:
          $ref: "#/components/schemas/PartyRoleChangeImpairmentDetails"
        isPartyBeneficiaryNonNatural:
          type: boolean
        isIrrevocable:
          type: boolean
        isRequiredMinimumDistributionDesignated:
          type: boolean
        preferredAddressId:
          type: string
        preferredEmailId:
          type: string
        preferredPhoneId:
          type: string
        isAddressSameAsOwner:
          type: string
    PartyRoleChangeIdentification:
      type: object
      properties:
        identificationType:
          type: string
          example: SSN
        identificationValue:
          type: string
          example: "123456789"
        issueState:
          type: string
          description: State of issue (e.g. AL)
        issueCountry:
          type: string
          description: Country of issue (e.g. US)
        identificationId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        identificationKey:
          type: string
        identificationDescription:
          type: string
    PartyRoleChangeAddress:
      type: object
      properties:
        addressId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        addressType:
          type: string
          example: HOME
        addressLine1:
          type: string
        addressLine2:
          type: string
        addressLine3:
          type: string
        city:
          type: string
        state:
          type: string
        zipCode:
          type: string
        zipCodeExtension:
          type: string
        country:
          type: string
        isPreferred:
          type: boolean
    PartyRoleChangePhone:
      type: object
      properties:
        phoneId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        phoneType:
          type: string
        countryCode:
          type: string
        areaCode:
          type: string
        dialNumber:
          type: string
        extension:
          type: string
        bestTime:
          type: string
        timeZone:
          type: string
        preferredPhoneIndicator:
          type: string
        isPreferred:
          type: boolean
    PartyRoleChangeEmail:
      type: object
      properties:
        emailId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        emailType:
          type: string
        emailAddress:
          type: string
        preferredEmailIndicator:
          type: string
        isPreferred:
          type: boolean
    PartyRoleChangeBankDetails:
      type: object
      description: Bank details associated with a party
      properties:
        bankId:
          type: string
        appliesToPartyId:
          type: string
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        nameOnAccount:
          type: string
        accountStatus:
          type: string
        accountType:
          type: string
        accountSubType:
          type: string
        accountNumber:
          type: string
        routingNumber:
          type: string
        internationalBankAccountNumber:
          type: string
        branchName:
          type: string
        branchAddress:
          $ref: "#/components/schemas/PartyRoleChangeAddress"
        branchPhoneNumber:
          type: string
        bankAccountPurpose:
          type: string
    PartyRoleChangeDeathDetails:
      type: object
      properties:
        dateOfDeath:
          type: string
          format: date
        causeOfDeath:
          type: string
        deathNotificationDate:
          type: string
          format: date
        dateOfDueProof:
          type: string
          format: date
    PartyRoleChangeImpairmentDetails:
      type: object
      properties:
        disabled:
          type: boolean
        disabilityStartDate:
          type: string
          format: date
  securitySchemes:
    Auth0:
      type: openIdConnect
      openIdConnectUrl: https://login.qa.zinnia.com/.well-known/openid-configuration
      x-kong-security-openid-connect:
        config:
          run_on_preflight: true
          scopes_claim:
            - https://qa.api.zinnia.io/permissions
          audience_claim:
            - aud
          audience_required:
            - https://qa.api.zinnia.io
          client_id:
            - client_id
          auth_methods:
            - bearer
        enabled: true
        protocols:
          - grpc
          - grpcs
          - http
          - https
```