---
title: "Transaction eligibility (V3)"
url: "https://developers.zinnia.com/apis/policy-transactions-1-0-2/versions/d0006570-ab9d-464e-814f-d120ba425e84/operations/evaluateTransactionEligibilityV3ByPolicy"
---

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

# Transaction eligibility (V3)

`POST` `/policy/v3/transactions/{planCode}/{policyNumber}/eligibility/transaction`

Operation ID: `evaluateTransactionEligibilityV3ByPolicy`

Same evaluation as V2 transaction eligibility (policy, user permission and restriction checks), returned as one result per check, action and target, grouped by transaction type. If the body is omitted or empty, all transactions configured for the plan are evaluated. `partyId` is extracted from the `Authorization` bearer token.

## Path parameters

- `planCode` (string, required) - Plan code (exact, case-sensitive).
- `policyNumber` (string, required) - Policy number (exact, case-sensitive).

## Request body

Content types: `application/json`

## Responses

- `200` - Eligibility evaluation completed.
- `400` - Invalid request — missing required fields or malformed input
- `401` - Missing or invalid bearer token
- `500` - Unexpected server error. Dependency failures (CIAM, Zahara) surface as COULD_NOT_DETERMINE on the affected section rather than a 500.

## 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/v3/transactions/{planCode}/{policyNumber}/eligibility/transaction:
    post:
      tags:
        - Transactions Eligibility
      summary: Transaction eligibility (V3)
      description: >
        Same evaluation as V2 transaction eligibility (policy, user permission
        and restriction checks),

        returned as one result per check, action and target, grouped by
        transaction type.


        If the body is omitted or empty, all transactions configured for the
        plan are evaluated.

        `partyId` is extracted from the `Authorization` bearer token.
      operationId: evaluateTransactionEligibilityV3ByPolicy
      parameters:
        - name: planCode
          in: path
          required: true
          schema:
            type: string
          description: Plan code (exact, case-sensitive).
          example: UL100
        - name: policyNumber
          in: path
          required: true
          schema:
            type: string
          description: Policy number (exact, case-sensitive).
          example: POL123456
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EligibilityV3Request"
            example:
              transactionGroup: FirstYearTxn
              transactionTypes:
                - RiderChange
                - DBOChange
      responses:
        "200":
          description: Eligibility evaluation completed.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/EligibilityV3TransactionResult"
              example:
                - transactionGroup: FirstYearTxn
                  transactionType: RiderChange
                  results:
                    - eligibilityType: POLICY
                      action: ADD
                      target:
                        type: RIDER
                        code: CITR
                      eligible: true
                    - eligibilityType: USER
                      action: ADD
                      target:
                        type: RIDER
                        code: CITR
                      eligible: true
                    - eligibilityType: POLICY
                      action: UPDATE
                      target:
                        type: RIDER
                        code: CITR
                      eligible: false
                      reasons:
                        - code: BPM.NM.050
                          message: The effective date entered is not within this policy's free look
                            period.
                          resolution: Update the effective date (if possible), or submit for NIGO
                            processing.
                - transactionGroup: FirstYearTxn
                  transactionType: DBOChange
                  results:
                    - eligibilityType: POLICY
                      action: ADD
                      target:
                        type: BENEFIT_OPTION
                        code: DBO
                      eligible: true
                    - eligibilityType: USER
                      action: ADD
                      target:
                        type: BENEFIT_OPTION
                        code: DBO
                      eligible: false
                      reasons:
                        - code: BPM.NM.051
                          message: The user is not authorized to perform this action on this policy.
                          resolution: Submit the request through an authorized user or for NIGO
                            processing.
                    - eligibilityType: RESTRICTION
                      action: ADD
                      target:
                        type: BENEFIT_OPTION
                        code: DBO
                      eligible: true
        "400":
          $ref: "#/components/responses/EligibilityBadRequest"
        "401":
          $ref: "#/components/responses/EligibilityUnauthorized"
        "500":
          $ref: "#/components/responses/EligibilityInternalServerError"
      security:
        - Auth0: []
security:
  - Auth0: []
components:
  schemas:
    EligibilityV3Request:
      type: object
      description: Optional request body. When omitted or empty, all configured
        transactions are evaluated.
      properties:
        transactionGroup:
          type: string
          description: Filter results to a specific transaction group.
          example: FirstYearTxn
        transactionTypes:
          type: array
          description: Filter results to specific transaction types.
          items:
            type: string
          example:
            - RiderChange
            - DBOChange
    EligibilityV3TransactionResult:
      type: object
      description: Eligibility evaluation results for a transaction type.
      required:
        - transactionType
        - results
      properties:
        transactionGroup:
          type: string
          description: Transaction group (from request or configuration).
          example: FirstYearTxn
        transactionType:
          type: string
          description: Transaction type.
          example: RiderChange
        results:
          type: array
          description: Eligibility check results for this transaction.
          items:
            $ref: "#/components/schemas/EligibilityV3CheckResult"
    EligibilityV3CheckResult:
      type: object
      description: Eligibility check result for a transaction, action, and target
        combination.
      required:
        - eligibilityType
        - action
        - target
        - eligible
      properties:
        eligibilityType:
          type: string
          description: Type of eligibility check.
          enum:
            - POLICY
            - USER
            - RESTRICTION
        action:
          type: string
          description: Action being evaluated.
          enum:
            - ADD
            - UPDATE
            - DELETE
            - INCREASE
            - DECREASE
            - NOT_APPLICABLE
        target:
          $ref: "#/components/schemas/EligibilityV3Target"
        eligible:
          type: boolean
          description: Whether the action is eligible for the target.
        reasons:
          type: array
          description: Reasons for ineligibility. Present only when eligible is false.
          items:
            $ref: "#/components/schemas/EligibilityV3Reason"
    EligibilityErrorResponse:
      type: object
      description: Error envelope returned by eligibility endpoints on 4xx/5xx responses.
      properties:
        status:
          type: integer
          example: 401
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: partyId claim could not be extracted
    EligibilityV3Target:
      type: object
      description: The target of the eligibility check.
      required:
        - type
        - code
      properties:
        type:
          type: string
          description: Target type.
          enum:
            - RIDER
            - COVERAGE
            - BENEFIT_OPTION
            - TRANSACTION
        code:
          type: string
          description: Target code or identifier.
          example: CITR
    EligibilityV3Reason:
      type: object
      description: Structured reason for an ineligible transaction.
      properties:
        code:
          type: string
          description: Machine-readable reason code.
          example: BPM.NM.050
        message:
          type: string
          description: Human-readable explanation.
          example: The effective date entered is not within this policy's free look
            period.
        resolution:
          type: string
          description: Suggested remediation.
          example: Update the effective date (if possible), or submit for NIGO processing.
  responses:
    EligibilityBadRequest:
      description: Invalid request — missing required fields or malformed input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EligibilityErrorResponse"
          example:
            status: 400
            error: Bad Request
            message: policyNumber is required
    EligibilityUnauthorized:
      description: Missing or invalid bearer token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EligibilityErrorResponse"
          example:
            status: 401
            error: Unauthorized
            message: partyId claim could not be extracted from token
    EligibilityInternalServerError:
      description: >
        Unexpected server error. Dependency failures (CIAM, Zahara) surface as
        COULD_NOT_DETERMINE on the affected section rather than a 500.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/EligibilityErrorResponse"
          example:
            status: 500
            error: Internal Server Error
  securitySchemes:
    Auth0:
      type: openIdConnect
      openIdConnectUrl: https://login.dev.zinnia.com/.well-known/openid-configuration
      x-kong-security-openid-connect:
        config:
          run_on_preflight: true
          scopes_claim:
            - https://dev.api.zinnia.io/permissions
          audience_claim:
            - aud
          audience_required:
            - https://dev.api.zinnia.io
          client_id:
            - client_id
          auth_methods:
            - bearer
        enabled: true
        protocols:
          - grpc
          - grpcs
          - http
          - https
```