---
title: "BeneficiaryPatch"
url: "https://developers.zinnia.com/apis/new-business/versions/b8532e16-b28e-4393-9305-def50b91e40e/schemas/BeneficiaryPatch"
---

> Full API specification: https://developers.zinnia.com/apis/new-business/versions/b8532e16-b28e-4393-9305-def50b91e40e.md

# BeneficiaryPatch

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: Zinnia New Business API.
  version: 0.9.8
servers:
  - url: https://qa.api.zinnia.io
    description: QA Environment
  - url: https://dev.api.zinnia.io
    description: DEV Environment
  - url: https://uat.api.zinnia.io
    description: UAT Environment
  - url: https://api.zinnia.io
    description: PROD Environment
components:
  schemas:
    RelationshipPatch:
      type: object
      properties:
        type:
          type: string
          enum:
            - TRUSTEE
            - TRUSTEEOFMINOR
            - TRUSTEEOFINCOMPETENT
            - POWEROFATTORNEY
            - CONTROLLINGPERSONOFENTITY
            - BROTHER
            - CHILD
            - DAUGHTER
            - DOMESTICPARTNER
            - EXECUTORS
            - FATHER
            - FIANCE
            - GRANDCHILD
            - GRANDPARENT
            - LIFEPARTNER
            - MOTHER
            - PARENT
            - SIBLING
            - SISTER
            - SON
            - SPOUSE
            - STEPFATHER
            - STEPMOTHER
            - STEPPARENT
            - SELF
            - LEGALGUARDIAN
            - BUSINESS
            - BUSINESSASSOCIATE
            - PARTNER
            - EMPLOYER
            - FORMERSPOUSE
            - OWNER
            - STEPCHILD
            - CUSTODIAN
            - OTHER
          example: SPOUSE
        percentage:
          type: integer
          minimum: 0
          maximum: 100
          example: 50
    TrustDetailsPatch:
      type: object
      properties:
        trustName:
          type: string
          description: Name of the trust
          example: Sunshine Family Trust
        trustType:
          type: string
          enum:
            - TESTAMENTARYTRUST
            - INTERVIVOSTRUST
            - INDIVIDUALTRUST
            - CORPORATETRUST
            - GRANTORTRUST
          description: Type of trust
          example: INDIVIDUALTRUST
        trustDate:
          type: string
          format: date
          description: Original date when the trust was established
          example: 2015-08-15
        amendedTrustDate:
          type: string
          format: date
          description: Date of last amendment to the trust
          example: 2021-04-10
        governingStateOfTrust:
          $ref: "#/components/schemas/State"
    OrganizationDetailsPatch:
      type: object
      properties:
        organizationName:
          type: string
          description: Legal name of the organization
          example: Northwest Financial Group LLC
        organizationDBAName:
          type: string
          description: Doing Business As (DBA) name of the organization
          example: NWF Group
        organizationShortName:
          type: string
          description: Short or abbreviated name of the organization
          example: NWF
        organizationCode:
          type: string
          description: Unique code identifying the organization
          example: ORG-00123
        entityType:
          type: string
          description: Legal entity type of the organization
          enum:
            - SOLEPROPRIETORSHIP
            - GENERALPARTNERSHIP
            - LIMITEDPARTNERSHIP
            - CCORPORATION
            - SCORPORATION
            - LIMITEDLIABILITYCOMPANY
            - CHARITABLEORGANIZATION
            - ESTATE
            - TRUST
            - CORPORATION
            - UNKNOWN
          example: LIMITEDLIABILITYCOMPANY
    PersonalInformationPrimaryPatch:
      type: object
      properties:
        firstName:
          type: string
          example: John
        middleName:
          type: string
          example: M
        lastName:
          type: string
          example: Doe
        suffix:
          type: string
          enum:
            - JR
            - SR
            - I
            - II
            - III
            - IV
            - V
            - VI
            - VII
          description: Suffix for given party if Applicable
          example: SR
        prefix:
          type: string
          enum:
            - MR
            - MS
            - MISS
            - DR.
            - MRS.
          description: Prefix for given party if Applicable
          example: MR
        dateOfBirth:
          type: string
          format: date
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
          example: 1990-01-01
          description: Date (with pattern "yyyy-mm-dd")
        gender:
          type: string
          enum:
            - MALE
            - FEMALE
            - UNISEX
          example: MALE
        birthSex:
          type: string
          enum:
            - MALE
            - FEMALE
            - UNISEX
          example: MALE
        birthState:
          $ref: "#/components/schemas/BirthState"
        birthCountry:
          $ref: "#/components/schemas/CountryV2"
        citizenCountry:
          $ref: "#/components/schemas/CountryV2"
    PassportIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/GovernmentIssuedIdentifierPatch"
        - type: object
          properties:
            countryOfIssue:
              $ref: "#/components/schemas/CountryV2"
    StateIdIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/GovernmentIssuedIdentifierPatch"
        - type: object
          properties:
            jurisdiction:
              $ref: "#/components/schemas/State"
    DriversLicenseIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/GovernmentIssuedIdentifierPatch"
        - type: object
          properties:
            jurisdiction:
              $ref: "#/components/schemas/State"
            restrictions:
              type: array
              items:
                type: string
              description: List of license restrictions
    SsnIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/IdentifierPatch"
        - type: object
          properties:
            lastFourOnly:
              type: boolean
              description: Indicates if only the last four digits are provided
              example: true
    ItinIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/IdentifierPatch"
        - type: object
          properties:
            issueYear:
              type: string
              pattern: ^\d{4}$
              description: Year when the ITIN was issued
              example: "2015"
    EinIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/IdentifierPatch"
        - type: object
          properties:
            issueYear:
              type: string
              pattern: ^\d{4}$
              description: Year when the EIN was issued
              example: "2015"
    AlienRegistrationIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/GovernmentIssuedIdentifierPatch"
        - type: object
          properties:
            countryOfOrigin:
              $ref: "#/components/schemas/CountryV2"
            category:
              type: string
              description: Immigration category or classification
              example: H-1B
    ExternalPartyIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/ExternalIdentifierPatch"
    AddressPatch:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the address
          example: 123e4567-e89b-12d3-a456-426614174000
        addressType:
          type: string
          enum:
            - RESIDENCE
            - BUSINESS
            - POBOX
            - SEASONAL
            - SECONDARY
            - MAILING
          description: Type of address
          example: RESIDENCE
        addressLine1:
          type: string
          description: Primary address line
          example: 123 Main St
        addressLine2:
          type: string
          description: Secondary address line (optional)
          example: Apt 4B
        addressLine3:
          type: string
          description: Secondary address line (optional)
          example: suite 123
        city:
          type: string
          description: City name
          example: San Francisco
        state:
          $ref: "#/components/schemas/State"
        zipCode:
          type: string
          pattern: ^\d{5}?$
          description: ZIP code (5 digits)
          example: "94105"
        zipCodeExt:
          type: string
          description: ZIP code extension
          example: "4465"
        country:
          type: string
          description: Country Code
          enum:
            - US
    PhoneNumberPatch:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the phone
          example: 123e4567-e89b-12d3-a456-426614174000
        type:
          type: string
          enum:
            - MOBILE
            - HOME
            - BUSINESS
            - CLAIMCENTER
            - CUSTOMERSERVICE
            - CORPORATEOFFICE
            - FAX
            - UNKNOWN
            - OTHER
          example: MOBILE
        countryCode:
          $ref: "#/components/schemas/CountryCallingCodes"
        areaCode:
          type: string
          example: "123"
        dialNumber:
          type: string
          example: 12345, 1234567890
        extension:
          type: string
          example: "1234"
        bestTime:
          type: string
          description: Best time
          example: Morning
        timezone:
          type: string
          description: Timezone for the entered phone details
          example: EST
    EmailPatch:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the email
          example: 123e4567-e89b-12d3-a456-426614174000
        type:
          type: string
          enum:
            - PERSONAL
            - BUSINESS
            - CUSTOMERSERVICE
            - OTHER
          example: PERSONAL
        address:
          type: string
          format: email
          example: j4TlS@example.com
    State:
      type: string
      example: CA
      enum:
        - AL
        - AK
        - AZ
        - AR
        - AS
        - AA
        - AE
        - AP
        - CA
        - CO
        - CT
        - DC
        - DE
        - FL
        - GA
        - GU
        - HI
        - ID
        - IL
        - IN
        - IA
        - KS
        - KY
        - LA
        - ME
        - MD
        - MA
        - MI
        - MN
        - MS
        - MO
        - MT
        - MP
        - NE
        - NV
        - NH
        - NJ
        - NM
        - NY
        - NC
        - ND
        - OH
        - OK
        - OR
        - PA
        - PR
        - RI
        - SC
        - SD
        - TN
        - TX
        - UT
        - UM
        - VT
        - VA
        - VI
        - WA
        - WV
        - WI
        - WY
      description: Abbreviated names for states
    BirthState:
      type: string
      example: CA
      enum:
        - AL
        - AK
        - AZ
        - AR
        - CA
        - CO
        - CT
        - DC
        - DE
        - FL
        - GA
        - HI
        - ID
        - IL
        - IN
        - IA
        - KS
        - KY
        - LA
        - ME
        - MD
        - MA
        - MI
        - MN
        - MS
        - MO
        - MT
        - NE
        - NV
        - NH
        - NJ
        - NM
        - NY
        - NC
        - ND
        - OH
        - OK
        - OR
        - PA
        - RI
        - SC
        - SD
        - TN
        - TX
        - UT
        - VT
        - VA
        - WA
        - WV
        - WI
        - WY
        - AN
        - XK
      description: Only applicable for US born party
    CountryV2:
      type: string
      example: US
      description: ISO Country Code
        https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes
      enum:
        - US
        - AF
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - CV
        - KH
        - CM
        - CA
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CD
        - CG
        - CK
        - CR
        - HR
        - CU
        - CW
        - CY
        - CZ
        - CI
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - SZ
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - NO
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - MK
        - RO
        - RU
        - RW
        - RE
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - XK
        - EH
        - YE
        - ZM
        - ZW
        - AX
    GovernmentIssuedIdentifierPatch:
      allOf:
        - $ref: "#/components/schemas/IdentifierPatch"
        - type: object
          properties:
            issueDate:
              type: string
              format: date
              pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
              example: 2015-08-15
              description: Date (with pattern "yyyy-mm-dd")
            expirationDate:
              type: string
              format: date
              pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
              example: 2025-08-15
              description: Date (with pattern "yyyy-mm-dd")
            status:
              $ref: "#/components/schemas/IdentifierStatus"
    IdentifierPatch:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/IdentifierType"
        value:
          type: string
          description: Value of the identifier
          example: "123456789"
        description:
          type: string
          description: Additional description or notes about this identifier
          example: identifier description
        source:
          type: string
          description: Source system or organization that issued this identifier
          example: State of California
    ExternalIdentifierPatch:
      type: object
      properties:
        type:
          $ref: "#/components/schemas/IdentifierType"
        key:
          type: string
          example: ecn
          description: name of the identifier document
        value:
          type: string
          description: Value of the identifier
          example: "123456789"
        description:
          type: string
          description: Additional description or notes about this identifier
          example: ecn number
        source:
          type: string
          description: Source system or organization that issued this identifier
          example: State of California
    CountryCallingCodes:
      type: string
      description: ISO Country calling Code
        https://en.wikipedia.org/wiki/List_of_telephone_country_codes
      enum:
        - "1"
        - "93"
        - "355"
        - "213"
        - 1-684
        - "376"
        - "244"
        - 1-264
        - "672"
        - 1-268
        - "54"
        - "374"
        - "297"
        - "61"
        - "43"
        - "994"
        - 1-242
        - "973"
        - "880"
        - 1-246
        - "375"
        - "32"
        - "501"
        - "229"
        - 1-441
        - "975"
        - "591"
        - "387"
        - "267"
        - "55"
        - "246"
        - "673"
        - "359"
        - "226"
        - "257"
        - "855"
        - "237"
        - "238"
        - 1-345
        - "236"
        - "235"
        - "56"
        - "86"
        - "53"
        - "61"
        - "57"
        - "269"
        - "243"
        - "242"
        - "682"
        - "506"
        - "225"
        - "385"
        - "53"
        - "357"
        - "420"
        - "45"
        - "253"
        - 1-767
        - 1-809
        - 1-829
        - "670"
        - "593 "
        - "20"
        - "503"
        - "240"
        - "291"
        - "372"
        - "251"
        - "500"
        - "298"
        - "679"
        - "358"
        - "33"
        - "594"
        - "689"
        - "262"
        - "241"
        - "220"
        - "995"
        - "49"
        - "233"
        - "350"
        - "44"
        - "30"
        - "299"
        - 1-473
        - "590"
        - 1-671
        - "502"
        - "224"
        - "245"
        - "592"
        - "509"
        - "672"
        - "39"
        - "504"
        - "852"
        - "36"
        - "354"
        - "91"
        - "62"
        - "98"
        - "964"
        - "353"
        - "972"
        - "39"
        - 1-876
        - "81"
        - "962"
        - "7"
        - "254"
        - "686"
        - "850"
        - "82"
        - "965"
        - "996"
        - "856"
        - "371"
        - "961"
        - "266"
        - "231"
        - "218"
        - "423"
        - "370"
        - "352"
        - "853"
        - "389"
        - "261"
        - "265"
        - "60"
        - "960"
        - "223"
        - "356"
        - "692"
        - "596"
        - "222"
        - "230"
        - "269"
        - "52"
        - "691"
        - "373"
        - "377"
        - "976"
        - 1-664
        - "212"
        - "258"
        - "95"
        - "264"
        - "674"
        - "977"
        - "31"
        - "599"
        - "687"
        - "64"
        - "505"
        - "227"
        - "234"
        - "683"
        - "672"
        - 1-670
        - "47"
        - "968"
        - "92"
        - "680"
        - "970"
        - "507"
        - "675"
        - "595"
        - "51"
        - "63"
        - "64"
        - "48"
        - "351"
        - 1-787
        - 1-939
        - "974 "
        - "262"
        - "40"
        - "7"
        - "7"
        - "250"
        - "290"
        - 1-869
        - 1-758
        - "508"
        - 1-784
        - "685"
        - "378"
        - "239"
        - "966"
        - "381"
        - "221"
        - "248"
        - "232"
        - "65"
        - "421"
        - "386"
        - "677"
        - "252"
        - "27"
        - "500"
        - "34"
        - "94"
        - "249"
        - "597"
        - "47"
        - "268"
        - "46"
        - "41"
        - "963"
        - "886"
        - "992"
        - "255"
        - "66"
        - "228"
        - "690"
        - "676"
        - 1-868
        - "216"
        - "90"
        - "993"
        - 1-649
        - "688"
        - "256"
        - "380"
        - "971"
        - "44"
        - "1"
        - "246"
        - "598"
        - "998"
        - "678"
        - "418"
        - "58"
        - "84"
        - 1-284
        - 1-340
        - "681"
        - "212"
        - "967"
        - "243"
        - "260"
        - "263"
    IdentifierStatus:
      type: string
      enum:
        - ACTIVE
        - EXPIRED
        - SUSPENDED
        - REVOKED
        - PENDING
      description: Status of the identifier document
      example: ACTIVE
    IdentifierType:
      type: string
      enum:
        - PASSPORT
        - STATEPHOTOID
        - DRIVERLICENSENUMBER
        - SSN
        - TIN
        - EIN
        - EXTERNAL
        - OTHER
      description: Type of identifier document
    BeneficiaryPatch:
      type: object
      properties:
        partyId:
          type: string
          description: Unique identifier for the party
          format: uuid
          example: 2ad51ecf-9923-437f-a6f0-70968e464cdb
        partyRole:
          type: string
          enum:
            - PRIMARYBENEFICIARY
            - CONTINGENTBENEFICIARY
          description: Type of party role
          example: PRIMARYBENEFICIARY
        partyType:
          type: string
          enum:
            - INDIVIDUAL
            - ORGANIZATION
            - TRUST
          description: Type of party
          example: INDIVIDUAL
        irrevocableBene:
          type: boolean
          default: false
          description: Indicates whether the beneficiary designation is irrevocable.
            Applicable only for the Beneficiary party and accepted regardless of
            the party type (individual, organization, or trust). Defaults to
            false when not provided.
          example: true
        beneficiaryShareMethod:
          type: string
          enum:
            - PER_STIRPES_DISTRIBUTION
          description: Share method for the beneficiary designation. Applicable only for
            the Beneficiary party and supported for both Primary and Contingent
            beneficiary roles. When not provided, no share method is sent to the
            system of record.
          example: PER_STIRPES_DISTRIBUTION
        relationship:
          $ref: "#/components/schemas/RelationshipPatch"
        personalInformation:
          oneOf:
            - $ref: "#/components/schemas/TrustDetailsPatch"
            - $ref: "#/components/schemas/OrganizationDetailsPatch"
            - $ref: "#/components/schemas/PersonalInformationPrimaryPatch"
        partyCommunication:
          type: string
          enum:
            - REGULARMAIL
            - EMAIL
            - PHONE
        identifiers:
          type: array
          items:
            anyOf:
              - $ref: "#/components/schemas/PassportIdentifierPatch"
              - $ref: "#/components/schemas/StateIdIdentifierPatch"
              - $ref: "#/components/schemas/DriversLicenseIdentifierPatch"
              - $ref: "#/components/schemas/SsnIdentifierPatch"
              - $ref: "#/components/schemas/ItinIdentifierPatch"
              - $ref: "#/components/schemas/EinIdentifierPatch"
              - $ref: "#/components/schemas/AlienRegistrationIdentifierPatch"
              - $ref: "#/components/schemas/ExternalPartyIdentifierPatch"
          description: Array of identifiers for this party
        address:
          type: object
          properties:
            preferredAddressId:
              type: string
              format: uuid
              example: 2ad51ecf-9923-437f-a6f0-70968e464cdb
            addresses:
              type: array
              items:
                $ref: "#/components/schemas/AddressPatch"
              description: List of addresses associated with this party
              example: []
        phoneNumber:
          type: object
          properties:
            preferredPhoneId:
              type: string
              format: uuid
              example: 2ad51ecf-9923-437f-a6f0-70968e464cdb
            phoneNumbers:
              type: array
              items:
                $ref: "#/components/schemas/PhoneNumberPatch"
              description: List of phone numbers associated with this party
              example: []
        email:
          type: object
          properties:
            preferredEmailId:
              type: string
              format: uuid
              example: 2ad51ecf-9923-437f-a6f0-70968e464cdb
            emails:
              type: array
              items:
                $ref: "#/components/schemas/EmailPatch"
              description: List of emails associated with this party
              example: []
```