--- title: "IriPolicyParties" url: "https://developers.zinnia.com/apis/policy-service-0-1-0/versions/8306e031-b41c-452a-a7ed-d73d65602086/schemas/IriPolicyParties" --- > Full API specification: https://developers.zinnia.com/apis/policy-service-0-1-0/versions/8306e031-b41c-452a-a7ed-d73d65602086.md # IriPolicyParties ## OpenAPI definition ```yaml openapi: 3.0.0 info: title: Policy Service version: 0.0.21 servers: - url: https://uat.api.zinnia.io components: schemas: IriPolicyParty: 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}$ relationships: type: array minItems: 1 maxItems: 6 items: $ref: "#/components/schemas/IriPartyRelationship" paymentForm: $ref: "#/components/schemas/IriPartyPaymentForm" allocationPercentage: type: number description: Percentage share assigned to the party. example: 100 minimum: 0 maximum: 100 bank: description: Financial institution details. allOf: - $ref: "#/components/schemas/IriPartyBank" address: description: Physical or mailing address details. allOf: - $ref: "#/components/schemas/IriPartyAddress" phones: description: Phone numbers associated with the party. type: array items: $ref: "#/components/schemas/IriPartyPhone" emails: description: Email addresses associated with the party. type: array items: $ref: "#/components/schemas/IriPartyEmail" identifications: description: Identifications associated with the party. type: array items: $ref: "#/components/schemas/IriPartyIdentification" taxWithholdingInstructions: description: Tax withholding instructions associated with the party. type: array items: $ref: "#/components/schemas/IriPartyTaxWithholdingInstruction" deathDetails: description: Death details associated with the party. allOf: - $ref: "#/components/schemas/IriPartyDeathDetails" required: - type - taxId - relationships IriPartyType: type: string description: Type of party. enum: - individual - entity IriPartyRelationship: type: string description: Relationships the party has to the policy. enum: - owner - jointOwner - annuitant - jointAnnuitant - primaryBeneficiary - contingentBeneficiary IriPartyPaymentForm: type: string description: Party-level payment form for the systematic program. enum: - DTCC - ACH - CHECK - WIRE - EXCHANGE IriPartyBank: type: object properties: bankId: type: string description: Bank identifier. example: BNK123 maxLength: 100 nameOnAccount: type: string description: Name on the bank account. example: JOHN Q PUBLIC maxLength: 100 accountStatus: $ref: "#/components/schemas/IriBankAccountStatus" accountType: $ref: "#/components/schemas/IriBankAccountType" accountNumber: type: string description: Bank account number. example: "0000123412341234" maxLength: 17 pattern: ^\d{4,17}$ routingNumber: type: string description: Routing number. example: "021000021" pattern: ^\d{9}$ branchName: type: string description: Branch name. example: Charlotte Main Branch maxLength: 100 required: - nameOnAccount - accountType - accountNumber - routingNumber IriPartyAddress: type: object properties: addressId: type: string description: Address identifier. example: ADDR001 maxLength: 100 addressType: $ref: "#/components/schemas/IriAddressType" addressLine1: type: string description: First line of the address. example: 123 Elm St maxLength: 100 addressLine2: type: string description: Second line of the address. example: Unit 5 maxLength: 100 addressLine3: type: string description: Third line of the address. example: Building B maxLength: 100 addressLine4: type: string description: Fourth line of the address. example: Floor 3 maxLength: 100 addressLine5: type: string description: Fifth line of the address. example: "Attn: Accounts" maxLength: 100 city: type: string description: City name. example: Charlotte maxLength: 100 state: type: string description: State code. example: NC pattern: ^[A-Z]{2}$ zipCode: type: string description: Zip code. example: "28202" pattern: ^[0-9A-Za-z -]{3,10}$ zipCodeExtension: type: string description: Zip code extension. example: "1234" pattern: ^[0-9A-Za-z]{1,4}$ country: type: string description: Country code. example: US pattern: ^[A-Z]{2}$ required: - addressType - addressLine1 - city - state - zipCode IriPartyPhone: type: object properties: startDate: type: string description: Date the phone record becomes effective. example: 2026-03-06 format: date endDate: type: string description: Date the phone record ends. example: 2027-03-06 format: date phoneType: $ref: "#/components/schemas/IriPhoneType" countryCode: type: string description: Country code of the phone. example: "+1" pattern: ^\+?[0-9]{1,3}$ areaCode: type: string description: Area code of the phone. example: "704" pattern: ^[0-9]{2,5}$ dialNumber: type: string description: Dial number of the phone. example: "5550123" pattern: ^[0-9]{4,12}$ extension: type: string description: Dial-in extension for the phone. example: "123" pattern: ^[A-Za-z0-9-]{1,10}$ bestTime: $ref: "#/components/schemas/IriPhoneBestTime" timezone: type: string description: Timezone for the entered phone details. example: America/New_York pattern: ^[A-Za-z_]+/[A-Za-z_]+(?:/[A-Za-z_]+)?$ isPreferred: type: boolean description: Whether this is the preferred phone number. example: true phoneId: type: string description: Record identifier for the phone. example: PH001 pattern: ^[A-Za-z0-9._-]{1,100}$ required: - countryCode - areaCode - dialNumber IriPartyEmail: type: object properties: startDate: type: string description: Date the email record becomes effective. example: 2026-03-06 format: date endDate: type: string description: Date the email record ends. example: 2027-03-06 format: date emailType: $ref: "#/components/schemas/IriEmailType" emailAddress: type: string description: Email address of the party. example: john.public@example.com format: email pattern: ^[^@\s]+@[^@\s]+\.[^@\s]+$ isPreferred: type: boolean description: Whether this is the preferred email address. example: true emailId: type: string description: Record identifier for the email. example: EM001 pattern: ^[A-Za-z0-9._-]{1,100}$ required: - emailAddress IriPartyIdentification: type: object properties: identificationId: type: string description: Identifier for the identification record. example: IDE-875 pattern: ^[A-Za-z0-9._-]{1,100}$ startDate: type: string description: Date the identification record becomes effective. example: 2026-03-06 format: date endDate: type: string description: Date the identification record ends. example: 2028-03-06 format: date identificationType: $ref: "#/components/schemas/IriIdentificationType" identificationKey: type: string description: Identification key. example: US-PPT pattern: ^[A-Za-z0-9._-]{1,100}$ identificationValue: type: string description: Identification value. example: "999888777" maxLength: 100 identificationDescription: type: string description: Description of the identifier. example: US Passport maxLength: 255 issueState: type: string description: State that issued the identification. example: NC pattern: ^[A-Z]{2}$ issueCountry: type: string description: Country that issued the identification. example: US pattern: ^[A-Z]{2}$ required: - startDate - endDate 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 IriPartyDeathDetails: type: object properties: dateOfDeath: type: string description: Date on which the insured or annuitant died. example: 2026-03-06 format: date causeOfDeath: type: string description: Documented reason or medical determination for death. example: Natural causes maxLength: 100 deathNotificationDate: type: string description: Date on which the carrier was notified of the death. example: 2026-03-07 format: date dateOfDueProof: type: string description: Date the appropriate death paperwork was received. example: 2026-03-10 format: date IriBankAccountStatus: type: string description: Status of the bank account. enum: - ACTIVEBANKACCOUNT - TERMINATEDBANKACCOUNT IriBankAccountType: type: string description: Type of the bank account. enum: - CHECKING - SAVINGS - CREDITCARDACCOUNT - DEBITCARDACCOUNT - BROKERAGEACCOUNT - CERTIFICATEOFDEPOSITACCOUNT IriAddressType: type: string description: Type of address. enum: - RESIDENCE - BUSINESS - POBOXSEASONAL - OTHER IriPhoneType: type: string description: Classification of the phone number. enum: - MOBILE - HOME - BUSINESS - CLAIMCENTER - CUSTOMERSERVICE - CORPORATEOFFICE - FAX - UNKNOWN - OTHER IriPhoneBestTime: type: string description: Best time to contact the party via phone. enum: - MORNING - AFTERNOON - EVENING - ANYTIME IriEmailType: type: string description: Type or category of the email address. enum: - PERSONAL - BUSINESS - CUSTOMERSERVICE - OTHER IriIdentificationType: type: string description: Type of identification. enum: - PASSPORT - STATEPHOTOID - DRIVERLICENSENUMBER - SSN - TIN - EXTERNAL - EIN - 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 IriPolicyParties: 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 parties: description: Individuals or entities associated with the policy, including identity, relationship, and servicing instructions. type: array items: $ref: "#/components/schemas/IriPolicyParty" required: - startIndex - itemsCount - totalItemsCount - parties ```