--- title: "Role" url: "https://developers.zinnia.com/apis/new-business-annuity/versions/45a989ab-c3aa-4f85-8f67-f05c41747ed7/schemas/Role" --- > Full API specification: https://developers.zinnia.com/apis/new-business-annuity/versions/45a989ab-c3aa-4f85-8f67-f05c41747ed7.md # Role ## OpenAPI definition ```yaml openapi: 3.1.0 info: title: Zinnia New Business Annuity API version: 0.6.0 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: Phone: type: object required: - phoneType - country - areaCode - number properties: phoneType: type: string description: This field capture the type of phone like Home Phone, Work Phone. One Phone mandatory for Owner and Annuitant enum: - MOBILE - HOME - BUS - FAX - OTHER - UNK - BUSINESSFAX - SECONDHOMEPHONE - HOMEFAX - MODEM example: BUS country: type: string enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - 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 - MK - MP - NO - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - 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 - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - AFG - ALA - ALB - DZA - ASM - AND - AGO - AIA - ATG - ARG - ARM - ABW - AUS - AUT - AZE - BHS - BHR - BGD - BRB - BLR - BEL - BLZ - BEN - BMU - BTN - BOL - BES - BIH - BWA - BRA - IOT - BRN - BGR - BFA - BDI - CPV - KHM - CMR - CAN - CYM - CAF - TCD - CHL - CHN - CXR - CCK - COL - COM - COG - COD - COK - CRI - CIV - HRV - CUB - CUW - CYP - CZE - DNK - DJI - DMA - DOM - ECU - EGY - SLV - GNQ - ERI - EST - SWZ - ETH - FLK - FRO - FJI - FIN - FRA - GUF - PYF - ATF - GAB - GMB - GEO - DEU - GHA - GIB - GRC - GRL - GRD - GLP - GUM - GTM - GGY - GIN - GNB - GUY - HTI - HMD - VAT - HND - HKG - HUN - ISL - IND - IDN - IRN - IRQ - IRL - IMN - ISR - ITA - JAM - JPN - JEY - JOR - KAZ - KEN - KIR - PRK - KOR - KWT - KGZ - LAO - LVA - LBN - LSO - LBR - LBY - LIE - LTU - LUX - MAC - MDG - MWI - MYS - MDV - MLI - MLT - MHL - MTQ - MRT - MUS - MYT - MEX - FSM - MDA - MCO - MNG - MNE - MSR - MAR - MOZ - MMR - NAM - NRU - NPL - NLD - NCL - NZL - NIC - NER - NGA - NIU - NFK - MKD - MNP - NOR - OMN - PAK - PLW - PSE - PAN - PNG - PRY - PER - PHL - PCN - POL - PRT - PRI - QAT - REU - ROU - RUS - RWA - BLM - SHN - KNA - LCA - MAF - SPM - VCT - WSM - SMR - STP - SAU - SEN - SRB - SYC - SLE - SGP - SXM - SVK - SVN - SLB - SOM - ZAF - SGS - SSD - ESP - LKA - SDN - SUR - SJM - SWE - CHE - SYR - TWN - TJK - TZA - THA - TLS - TGO - TKL - TON - TTO - TUN - TUR - TKM - TCA - TUV - UGA - UKR - ARE - GBR - USA - UMI - URY - UZB - VUT - VEN - VNM - VGB - VIR - WLF - ESH - YEM - ZMB - ZWE description: Country codes zip: type: string description: ZIP code example: "10100" zipSuffix: type: string description: ZIP code suffix example: "1010" areaCode: type: string description: This field stores the telephone Area Code of client address example: "404" number: type: string description: This field stores the phone number. example: 1234567890 or 1234567 extension: type: string description: This field stores the Extension number example: "4560" Address: type: object required: - addressType - addressLine1 - city - state - zip - country properties: addressType: type: string required: - addressType description: Address Type of the Company enum: - RES - BUS - SECONDARY - POBOX - SEASONAL - MAILING example: BUS addressLine1: type: string description: Address Line 1 example: 100 ABC Street addressLine2: type: string description: Address Line 2 example: Suite 200 addressLine3: type: string description: Address Line 3 example: Topeka, KS 66601 city: type: string description: City Name example: Topeka state: type: string enum: - AA - AE - AK - AL - AP - AR - AZ - CA - CO - CT - DC - DE - FL - GA - HI - IA - ID - IL - IN - KS - KY - LA - MA - MD - ME - MI - MN - MO - MS - MT - NC - ND - NE - NH - NJ - NM - NV - NY - OH - OK - OR - PA - RI - SC - SD - TN - TX - UT - VA - VT - WA - WI - WV - WY description: State code example: KS zip: type: string format: 5 digits description: ZIP code example: "66601" zipSuffix: type: string format: 4 digits description: ZIP code suffix example: "0148" country: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AN - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - NO - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - XK - YE - YT - ZA - ZM - ZW description: Country codes example: US Email: type: object properties: emailId: type: string format: email description: Email address of associated party example: abc@zinnia.com emailType: type: string enum: - BUSINESS - PERSONAL description: This field captures the type of email address like business or personal email. BankInformation: type: object required: - bankName - abaNumber - accountNumber - bankingType properties: bankName: type: string description: Bank name example: ABC Bank abaNumber: type: string pattern: \d{9} description: ABA number minLength: 9 maxLength: 9 example: "123456789" ibaNumber: type: string description: International Bank Account Number example: US12KBDE89571012345678 accountNumber: type: string description: Account Number example: "1000000000" bankingType: type: string enum: - CHECKING - SAVINGS - CREDITCARD - DEBITCARD - BRKACCT - COD example: CHECKING Role: type: object required: - roleType - rolePercentage - nameType - lastName - dob - sex - phones - addresses - eDelivery - citizenshipCountry properties: roleType: type: string enum: - OWN - JNTOWN - PRIMBENE - CONTBENE - MRDDESGBENE - EXCCOMPANY - ANN - JNTANN - PAYOR - PAYEE - ASSIGNEE - PRIMWRITAGT - ADDWRITAGT - NONCOMAGT - PRIMSERAGT description: Role type. Owner, Annuitant, Servicing Agent and Writing Agent are mandatory. example: OWN rolePercentage: type: string required: - rolePercentage description: string($9(01) V9(09) for percentage. Total percentage of a role should be 100%. example: "100" nameType: type: string enum: - IND - ORG - TRUST - OTHER - UGMA - COMPANY description: The name type associated with the role. example: IND firstName: type: string description: First name of the party role example: firstName when name type is Natural/Individual middleName: type: string description: Middle name of the party role example: B lastName: type: string description: Last name of the party role example: Doe prefix: type: string description: Prefix example: Dr suffix: type: string description: Suffix example: Sr dob: type: string format: date pattern: ([0-9]{4})-([0-9]{2})-([0-9]{2}) description: Date of birth of party role. Mandatory for Owner and Annuitant (with pattern "yyyy-mm-dd"). example: 2023-12-19 sex: type: string enum: - MALE - FEMALE - UNISEX - OTHER description: Any one of the possible value for the gender.Mandatory for Owner and Annuitant. example: MALE citizenshipCountry: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AN - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - NO - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - USA - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - XK - YE - YT - ZA - ZM - ZW description: Country codes, Mandatory for Owner and Annuitant. taxId: type: string pattern: \d{9} description: 9 digit Social Security number. Mandatory for Owner , Annuitant and Agent. minLength: 9 maxLength: 9 example: "123456789" agentCRD: type: string description: CRD number for the party role, used as Agent Identifier. example: "123456" agentNPN: type: string description: NPN number for the agent, used as Agent Identifier. example: "123456" agentDistributorAgentAssignedId: type: string description: Distributor assigned Id for an agent, used as Agent Identifier. example: ABC0000000 agentCarrierAgentAssignedId: type: string description: Internal identifier assigned to the agent by carrier, used as Agent Identifier. example: ABC0000000 agentExternalId: type: string description: Unique number assigned by the MCS system, used as Agent Identifier. example: ABC0000000 phones: type: array description: One phone is mandatory for Owner and Annuitant items: $ref: "#/components/schemas/Phone" relationship: type: string enum: - TRUSTEE - TRUSTEEOFMINOR - BROTHER - CHILD - DAUGHTER - FATHER - FIANCEE - GRANDCHILD - LIFEPARTNER - MOTHER - SISTER - SON - SPOUSE - STEPFATHER - STEPMOTHER - SELF - OTHER - GRANDFATHER - GRANDMOTHER - DOMPARTNER - AUNT - NEPHEW - NIECE - HUSBAND - WIFE - UNCLE - EMPLOYER - GRANDPARENT - LEGALGUARDIAN - TRUSTEEOFINCOMP - PWROFATTRNY - CNTRLNGPRSNOFENT - EXECUTORS - ASSOCIATE - PARTNER - ESTATE - TRUST - GRANDSON - GRANDDAUGHTER - PARENT - NONSPOUSE - CHILDRENEQUALLY - CHILDRENPERSTIRPES - PERSTIRPES - SURVIVNGSPOUSE description: Relationship code example: SELF addresses: type: array description: One address is mandatory for Owner and Annuitant items: $ref: "#/components/schemas/Address" trustType: type: string enum: - INDIVIDUAL - CORPORATE description: Type of trust & TrustType is required when the role is a trust example: INDIVIDUAL eDelivery: type: string description: eDelivery is required/not for the role enum: - YES - NO example: YES emails: type: array description: Email for associated party, email is required when eDelivery is 'Y'. items: $ref: "#/components/schemas/Email" bankInformation: $ref: "#/components/schemas/BankInformation" dod: type: string pattern: ([0-9]{4})-([0-9]{2})-([0-9]{2}) description: Date of Death (with pattern "yyyy-mm-dd") example: 2023-12-19 ```