--- title: "Submit Initial Death Claim Transaction" url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/operations/submitInitialDeathClaim" --- > Full API specification: https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84.md # Submit Initial Death Claim Transaction `POST` `/bpm/v1/policies/{planCode}/{policyNumber}/initialdeathclaim` Operation ID: `submitInitialDeathClaim` Submits an initial death claim notification for the given policy. ## Path parameters - `planCode` (string, required) - Plan Code - `policyNumber` (string, required) - Policy Number ## Request body (required) Content types: `application/json` ## Responses - `202` - Submit Transaction Successful - `400` - Invalid request body. One or more fields failed validation. - `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.8 servers: - url: https://dev.api.zinnia.io description: DEV Environment - url: https://qa.api.zinnia.io description: QA Environment paths: /bpm/v1/policies/{planCode}/{policyNumber}/initialdeathclaim: post: tags: - Financial Transactions summary: Submit Initial Death Claim Transaction description: Submits an initial death claim notification for the given policy. operationId: submitInitialDeathClaim parameters: - name: planCode in: path required: true schema: type: string description: Plan Code example: EVIU101 - name: policyNumber in: path required: true schema: type: string description: Policy Number example: EVIUL7RED022 requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/InitialDeathClaimRequest" examples: initialDeathClaimExample: summary: Initial death claim request example description: > Nullable fields (endDate, extension, bestTime, timezone) are omitted when not applicable; the schema marks them nullable for explicit JSON null. value: correlationId: 381ee1cc-7f34-47b1-a007-948d26b68a0f effectiveDate: 2026-07-15 transactionReason: DEATH_NOTIFICATION externalIdentifiers: externalTransactionId: string referenceNumber: string policy: policyNumber: EVIUL7RED022 productType: LIFE lineOfBusiness: LIFE isContestable: true isFuneralHomeAssigned: false parties: - partyId: e6954b3d-a0ef-47dc-ac49-046db6bc7da7 partyRole: OTHER partyType: INDIVIDUAL isNotifier: true relationshipToInsured: BROTHER personalInformation: firstName: string middleName: string lastName: string suffix: string prefix: string dateOfBirth: 1990-01-01 gender: MALE birthSex: MALE birthCountry: US citizenCountry: US partyCommunication: REGULARMAIL identifiers: - type: SSN value: string description: Social Security Number source: SSA issueDate: 2015-01-01 expirationDate: 2070-01-01 status: ACTIVE countryOfIssue: US address: preferredAddressId: "1" addresses: - addressId: "1" startDate: 2026-05-13 addressType: RESIDENCE addressLine1: 1112 Pickle Street addressLine2: South Jersey addressLine3: 1234 Post box city: Garden City state: AL zipCode: "67846" zipCodeExtension: "23" country: US isPreferred: true phoneNumber: preferredPhoneId: "1" phones: - phoneId: "1" startDate: 2026-05-13 phoneType: MOBILE countryCode: "1" areaCode: "973" dialNumber: "765789" isPreferred: true email: preferredEmailId: "1" emails: - emailId: "1" startDate: 2026-05-13 emailType: PERSONAL emailAddress: informant@example.com isPreferred: true - partyId: 5c08cdb2d3c6428c966f9a86d536c607 partyRole: INSURED partyType: INDIVIDUAL personalInformation: firstName: string middleName: string lastName: string suffix: string prefix: string dateOfBirth: 1990-01-01 gender: MALE birthSex: MALE birthCountry: US citizenCountry: US partyCommunication: REGULARMAIL identifiers: - type: SSN value: string description: Social Security Number source: SSA issueDate: 2015-01-01 expirationDate: 2070-01-01 status: ACTIVE countryOfIssue: US - partyId: e6954b3d-a0ef-47dc-ac49-046db6bc7da7 partyRole: PRIMARYBENEFICIARY partyType: INDIVIDUAL relationshipToInsured: SPOUSE personalInformation: firstName: BENEFICIARY1 middleName: string lastName: string suffix: string prefix: string dateOfBirth: 1990-01-01 gender: MALE birthSex: MALE birthCountry: US citizenCountry: US partyCommunication: REGULARMAIL identifiers: - type: SSN value: string description: Social Security Number source: SSA issueDate: 2015-01-01 expirationDate: 2070-01-01 status: ACTIVE countryOfIssue: US address: preferredAddressId: "1" addresses: - addressId: "1" startDate: 2026-05-13 addressType: RESIDENCE addressLine1: 1112 Pickle Street addressLine2: South Jersey addressLine3: 1234 Post box city: Garden City state: AL zipCode: "67846" zipCodeExtension: "23" country: US isPreferred: true phoneNumber: preferredPhoneId: "1" phones: - phoneId: "1" startDate: 2026-05-13 phoneType: MOBILE countryCode: "1" areaCode: "973" dialNumber: "765789" isPreferred: true email: preferredEmailId: "1" emails: - emailId: "1" startDate: 2026-05-13 emailType: PERSONAL emailAddress: informant@example.com isPreferred: true - partyId: uuid-PRIMARYBENEFICIARY2 partyRole: PRIMARYBENEFICIARY partyType: INDIVIDUAL relationshipToInsured: SPOUSE personalInformation: firstName: BENEFICIARY2 middleName: string lastName: string suffix: string prefix: string dateOfBirth: 1990-01-01 gender: MALE birthSex: MALE birthCountry: US citizenCountry: US partyCommunication: REGULARMAIL identifiers: - type: SSN value: string description: Social Security Number source: SSA issueDate: 2015-01-01 expirationDate: 2070-01-01 status: ACTIVE countryOfIssue: US address: preferredAddressId: "1" addresses: - addressId: "1" startDate: 2026-05-13 addressType: RESIDENCE addressLine1: 1112 Pickle Street addressLine2: South Jersey addressLine3: 1234 Post box city: Garden City state: AL zipCode: "67846" zipCodeExtension: "23" country: US isPreferred: true phoneNumber: preferredPhoneId: "1" phones: - phoneId: "1" startDate: 2026-05-13 phoneType: MOBILE countryCode: "1" areaCode: "973" dialNumber: "765789" isPreferred: true email: preferredEmailId: "1" emails: - emailId: "1" startDate: 2026-05-13 emailType: PERSONAL emailAddress: beneficiary@example.com isPreferred: true deathNotification: partyId: 5c08cdb2d3c6428c966f9a86d536c607 partyRole: INSURED notificationReceivedDate: 2026-07-11 proofOfDeathReceived: false certifiedReceivedDate: 2025-12-15 claimStatus: PENDING deathDetails: dateOfDeath: 2025-12-15 locationOfDeath: string countryOfDeath: US causeOfDeath: NATURALDEATH documents: - documentType: DEATH_CERTIFICATE documentName: Certified Death Certificate - John Smith documentId: EDS-DOC-987654321 - documentType: CLAIMANT_FORM documentName: Claimant Statement - Jane Smith documentId: EDS-DOC-987654322 riderClaim: - riderCode: CHILD_TERM riderName: Child Term Rider riderElected: true partyId: e6954b3d-a0ef-47dc-ac49-046db6bc7da7 - riderCode: WAIVER_OF_PREMIUM riderName: Waiver of Premium Rider riderElected: false partyId: 5c08cdb2d3c6428c966f9a86d536c607 responses: "202": description: Submit Transaction Successful content: application/json: schema: $ref: "#/components/schemas/TransactionAcceptedResponse" examples: success: summary: Accepted death claim submission value: correlationId: 3a2a3435-2089-4b81-9959-e0d569ccf4f0 caseId: CA0000369469 caseStatus: IN_PROGRESS "400": description: Invalid request body. One or more fields failed validation. content: application/json: schema: $ref: "#/components/schemas/TransactionResponse" examples: failure: $ref: "#/components/examples/failureTransactionResponse" "500": description: Internal server error. Please check server logs for more details. content: application/json: schema: $ref: "#/components/schemas/TransactionResponse" examples: serverError: summary: Internal server error description: > When no specific field caused the failure, omit attribute or send JSON null per schema. value: status: failure error: - errorCode: BPM.SYS.500 error: An unexpected internal server error occurred. resolution: Contact platform support with the correlationId. security: - Auth0: [] security: - Auth0: [] components: schemas: InitialDeathClaimRequest: type: object required: - effectiveDate - transactionReason - parties - deathNotification properties: correlationId: type: string description: Unique identifier used by every system to trace the request example: 3a2a3435-2089-4b81-9959-e0d569ccf4f0 effectiveDate: type: string format: date example: 2025-12-15 description: Date (with pattern "yyyy-mm-dd") when the death claim transaction was originally scheduled or expected to happen. It can be a non-business day transactionReason: type: string enum: - DEATH_NOTIFICATION description: Reason for the transaction example: DEATH_NOTIFICATION externalIdentifiers: type: object properties: externalTransactionId: type: string example: EXT-TXN-20251215-001 referenceNumber: type: string example: REF-20251215-001 policy: $ref: "#/components/schemas/DeathClaimPolicy" parties: type: array items: $ref: "#/components/schemas/DeathClaimParty" deathNotification: $ref: "#/components/schemas/DeathNotification" documents: type: array description: Supporting documents associated with the death claim (e.g. certified death certificate). items: $ref: "#/components/schemas/DeathClaimDocument" riderClaim: type: array description: Rider claims applicable to the policy. Each entry links the elected rider to the party it applies to. items: $ref: "#/components/schemas/DeathClaimRiderClaim" 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 TransactionResponse: type: object properties: status: type: string enum: - success - failure error: type: array items: $ref: "#/components/schemas/Error" quoteResponse: type: object DeathClaimPolicy: type: object required: - policyNumber - productType - lineOfBusiness properties: policyNumber: type: string example: POL-20251215-001 productType: type: string description: Type of product example: FIXEDINDEXEDANNUITY lineOfBusiness: type: string enum: - LIFE - ANNUITY description: Line of business example: LIFE isContestable: type: boolean description: Indicates whether the policy is within the contestability period at the time of death. example: true isFuneralHomeAssigned: type: boolean description: Indicates whether a funeral home has been assigned against the policy. example: false DeathClaimParty: type: object required: - partyId - partyRole - partyType properties: partyId: type: string description: Unique identifier for the party example: 2f356dcc-303d-4fc0-94a2-5369fb62642a partyRole: type: string enum: - INSURED - OWNER - JOINTOWNER - ANNUITANT - JOINTANNUITANT - PRIMARYBENEFICIARY - CONTINGENTBENEFICIARY - COVEREDINSURED - PRIMARYSERVICINGAGENT - OTHER example: PRIMARYBENEFICIARY partyType: type: string enum: - INDIVIDUAL - ORGANIZATION example: INDIVIDUAL relationshipToInsured: type: string enum: - SPOUSE - CHILD - PARENT - SIBLING - BROTHER - SISTER - OTHER example: SPOUSE isNotifier: type: boolean description: Indicates whether this party is the notifier of the death claim. example: true personalInformation: $ref: "#/components/schemas/PersonalInformation" partyCommunication: type: string enum: - REGULARMAIL - EMAIL - PHONE identifiers: type: array items: $ref: "#/components/schemas/PartyIdentifier" address: $ref: "#/components/schemas/PartyAddress" phoneNumber: $ref: "#/components/schemas/PartyPhoneNumber" email: $ref: "#/components/schemas/PartyEmail" DeathNotification: type: object required: - partyId - notificationReceivedDate - claimStatus - deathDetails properties: partyId: type: string description: Identifier of the deceased party. Must match the partyId of one of the parties in the request. example: 2f4c4f6d-7b3e-4d0d-b9e8-8f3a4f0c2201 partyRole: type: string enum: - INSURED - OWNER - JOINTOWNER - PRIMARYBENEFICIARY - ANNUITANT - COVEREDINSURED description: Role held by the deceased party on the policy. example: INSURED notificationReceivedDate: type: string format: date example: 2025-12-15 description: Date (with pattern "yyyy-mm-dd") proofOfDeathReceived: type: boolean example: false certifiedReceivedDate: type: string format: date example: 2025-12-15 description: Date (with pattern "yyyy-mm-dd") claimStatus: type: string enum: - PENDING - APPROVED - DENIED - IN_PROGRESS example: PENDING deathDetails: $ref: "#/components/schemas/DeathDetails" DeathClaimDocument: type: object properties: documentType: type: string description: Type of the supporting document. example: DEATH_CERTIFICATE documentName: type: string description: Human-readable name of the document. example: Certified Death Certificate - John Smith documentId: type: string description: Identifier of the document in the Enterprise Document Store (EDS). example: EDS-DOC-987654321 DeathClaimRiderClaim: type: object properties: riderCode: type: string description: Code identifying the rider on the policy. example: CHILD_TERM riderName: type: string description: Display name of the rider. example: Child Term Rider riderElected: type: boolean description: Whether the rider was elected on the policy. example: true partyId: type: string description: Identifier of the party the rider claim applies to. Must match the partyId of one of the parties in the request. example: 4a2d8c01-9a1d-4f35-8f0b-3e6d3b7d3301 Error: type: object properties: errorCode: type: string example: BPM.NM.002 description: This is the NIGO id generated by BPM system attribute: type: string error: type: string description: This is the error generated by BPM system resolution: type: string description: Resolution generated by BPM system to resolve the error PersonalInformation: type: object properties: firstName: type: string example: Jane middleName: type: string example: Marie lastName: type: string example: Smith suffix: type: string example: Jr. prefix: type: string example: Ms. dateOfBirth: type: string format: date example: 1990-01-01 description: Date (with pattern "yyyy-mm-dd") gender: type: string enum: - MALE - FEMALE - OTHER birthSex: type: string enum: - MALE - FEMALE birthCountry: type: string example: US citizenCountry: type: string example: US PartyIdentifier: type: object properties: type: type: string enum: - SSN - EIN - TIN value: type: string example: 123-45-6789 description: type: string example: Social Security Number source: type: string example: SSA issueDate: type: string format: date example: 2015-01-01 description: Date (with pattern "yyyy-mm-dd") expirationDate: type: string format: date nullable: true example: 2070-01-01 description: Date (with pattern "yyyy-mm-dd") status: type: string enum: - ACTIVE - INACTIVE example: ACTIVE countryOfIssue: type: string example: US PartyAddress: type: object properties: preferredAddressId: type: string example: "1" addresses: type: array items: $ref: "#/components/schemas/AddressDetail" PartyPhoneNumber: type: object properties: preferredPhoneId: type: string example: "1" phones: type: array items: $ref: "#/components/schemas/PhoneDetail" PartyEmail: type: object properties: preferredEmailId: type: string example: "1" emails: type: array items: $ref: "#/components/schemas/EmailDetail" DeathDetails: type: object properties: dateOfDeath: type: string format: date example: 2025-12-15 description: Date (with pattern "yyyy-mm-dd") locationOfDeath: type: string example: Newark, NJ countryOfDeath: type: string enum: - US - CA - RU - EG - ZA - GR - NL - BE - FR - ES - HU - IT - RO - CH - AT - GB - DK - SE - NO - PL - DE - PE - MX - CU - AR - BR - CL - CO - VE - MY - AU - ID - PH - NZ - SG - TH - JP - VN - CN - TR - IN - PK - AF - LK - IR - MA - DZ - TN - LY - GM - SN - MR - ML - GN - BF - NE - TG - BJ - MU - LR - SL - GH - NG - CF - TD - CM - CV - ST - GQ - GA - BS - AO - BB - AX - SD - RW - ET - SO - DJ - KE - TZ - UG - BI - MZ - ZM - MG - RE - ZW - NA - MW - LS - BW - AG - KM - GW - CD - VG - SH - AW - FO - GL - KY - GI - PT - LU - IE - IS - AL - MT - CY - FI - BG - GG - LT - LV - EE - MD - AM - BY - AD - SM - UA - HR - SI - BA - MK - XK - CZ - SK - LI - BM - GD - FK - BZ - GT - SV - HN - NI - CR - PM - HT - PR - VI - GS - SX - BQ - GP - BO - GY - EC - GF - PY - MQ - SR - UY - AN - TC - BL - MF - MS - GU - AQ - BN - NR - PG - TO - SB - VU - FJ - WF - CK - NU - AS - KI - NC - TV - PF - MP - PW - MH - FM - SS - LC - DM - VC - DO - HK - MO - KH - LA - TT - KN - JM - BD - TW - MM - KR - KP - LB - JO - SY - IQ - KW - SA - YE - OM - AE - IL - BH - QA - BT - NP - TJ - TM - AZ - GE - UZ - AI - PA - CI - ER - KZ - KG - CC - MN - BV - SC - IO - WS - TL - TF - YT - PN - SJ - TK - UM - EH - MV - CX - NF - CW - CG - MC - VA - SZ - PS - JE - IM - RS - ME - HM description: Abbreviated names for countries causeOfDeath: type: string enum: - NATURALDEATH - ACCIDENT - SUICIDE - HOMICIDE - PENDINGINVESTIGATION - UNKNOWN description: Manner or cause of the death, when known. example: NATURALDEATH AddressDetail: type: object properties: addressId: type: string example: "1" startDate: type: string format: date example: 2026-05-13 description: Date (with pattern "yyyy-mm-dd") endDate: type: string format: date nullable: true description: Date (with pattern "yyyy-mm-dd"). Omit or send JSON null when not applicable. addressType: type: string enum: - RESIDENCE - MAILING - BUSINESS - OTHER - SEASONAL example: RESIDENCE addressLine1: type: string example: 1112 Pickle Street addressLine2: type: string example: South Jersey addressLine3: type: string example: 1234 Post box city: type: string example: Garden City state: type: string 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 description: Abbreviated names for states zipCode: type: string example: "67846" zipCodeExtension: type: string example: "23" country: type: string enum: - US - CA - RU - EG - ZA - GR - NL - BE - FR - ES - HU - IT - RO - CH - AT - GB - DK - SE - NO - PL - DE - PE - MX - CU - AR - BR - CL - CO - VE - MY - AU - ID - PH - NZ - SG - TH - JP - VN - CN - TR - IN - PK - AF - LK - IR - MA - DZ - TN - LY - GM - SN - MR - ML - GN - BF - NE - TG - BJ - MU - LR - SL - GH - NG - CF - TD - CM - CV - ST - GQ - GA - BS - AO - BB - AX - SD - RW - ET - SO - DJ - KE - TZ - UG - BI - MZ - ZM - MG - RE - ZW - NA - MW - LS - BW - AG - KM - GW - CD - VG - SH - AW - FO - GL - KY - GI - PT - LU - IE - IS - AL - MT - CY - FI - BG - GG - LT - LV - EE - MD - AM - BY - AD - SM - UA - HR - SI - BA - MK - XK - CZ - SK - LI - BM - GD - FK - BZ - GT - SV - HN - NI - CR - PM - HT - PR - VI - GS - SX - BQ - GP - BO - GY - EC - GF - PY - MQ - SR - UY - AN - TC - BL - MF - MS - GU - AQ - BN - NR - PG - TO - SB - VU - FJ - WF - CK - NU - AS - KI - NC - TV - PF - MP - PW - MH - FM - SS - LC - DM - VC - DO - HK - MO - KH - LA - TT - KN - JM - BD - TW - MM - KR - KP - LB - JO - SY - IQ - KW - SA - YE - OM - AE - IL - BH - QA - BT - NP - TJ - TM - AZ - GE - UZ - AI - PA - CI - ER - KZ - KG - CC - MN - BV - SC - IO - WS - TL - TF - YT - PN - SJ - TK - UM - EH - MV - CX - NF - CW - CG - MC - VA - SZ - PS - JE - IM - RS - ME - HM description: Abbreviated names for countries isPreferred: type: boolean example: true PhoneDetail: type: object properties: phoneId: type: string example: "1" startDate: type: string format: date example: 2026-05-13 description: Date (with pattern "yyyy-mm-dd") endDate: type: string format: date nullable: true description: Date (with pattern "yyyy-mm-dd"). Omit or send JSON null when not applicable. phoneType: type: string enum: - MOBILE - HOME - WORK example: MOBILE countryCode: type: string example: "1" areaCode: type: string example: "973" dialNumber: type: string example: "7657890" extension: type: string nullable: true description: Omit or send JSON null when not applicable. bestTime: type: string nullable: true description: Omit or send JSON null when not applicable. timezone: type: string nullable: true description: Omit or send JSON null when not applicable. isPreferred: type: boolean example: true EmailDetail: type: object properties: emailId: type: string example: "1" startDate: type: string format: date example: 2026-05-13 description: Date (with pattern "yyyy-mm-dd") endDate: type: string format: date nullable: true description: Date (with pattern "yyyy-mm-dd"). Omit or send JSON null when not applicable. emailType: type: string enum: - PERSONAL - WORK - BUSINESS - CUSTOMERSERVICE - OTHER example: PERSONAL emailAddress: type: string format: email example: informant@example.com description: Type of the email. PERSONAL for personal emails, BUSINESS for business emails, CUSTOMERSERVICE for customer service emails, OTHER for any other type of emails. isPreferred: type: boolean example: true examples: failureTransactionResponse: value: status: failure validationResult: - errorCode: BPM.NM.005 attribute: null error: Amount request is invalid. resolution: Please check the One Time Premium Amount and submit the request again. - errorCode: BPM.NM.003 attribute: null error: Party information does not match with information in the Zahara system. resolution: Please validate the party information and submit the request again. 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 ```