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

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

# Transaction eligibility

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

Operation ID: `evaluateTransactionEligibilityByPolicy`

Evaluates whether the authenticated user may perform specific transactions on the given policy. Runs three checks: product level eligibility, user permissions , and policy restrictions restrictions. If `items` is omitted or empty, all transactions configured for the plan are evaluated. `partyId` is extracted from the `Authorization` bearer token — it is never a body field.

## 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. One result entry per evaluated subject.
- `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.8
servers:
  - url: https://dev.api.zinnia.io
    description: DEV Environment
  - url: https://qa.api.zinnia.io
    description: QA Environment
paths:
  /policy/v2/transactions/{planCode}/{policyNumber}/eligibility/transaction:
    post:
      tags:
        - Transactions Eligibility
      summary: Transaction eligibility
      description: >
        Evaluates whether the authenticated user may perform specific
        transactions on the

        given policy. Runs three checks: product level eligibility, user
        permissions

        , and policy restrictions restrictions.


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

        `partyId` is extracted from the `Authorization` bearer token — it is
        never a body field.
      operationId: evaluateTransactionEligibilityByPolicy
      parameters:
        - name: planCode
          in: path
          required: true
          schema:
            type: string
          description: Plan code (exact, case-sensitive).
          example: ANN100
        - 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/EligibilityRequest"
            examples:
              specificTransactions:
                summary: Evaluate specific transactions
                value:
                  items:
                    - FullSurrender
                    - PartialWithdrawalOneTime
              allPlanTransactions:
                summary: Evaluate all configured plan transactions (empty body)
                value: {}
      responses:
        "200":
          description: Eligibility evaluation completed. One result entry per evaluated
            subject.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EligibilityResponse"
              examples:
                eligible:
                  summary: Transaction eligible
                  value:
                    eligibilityType: transaction
                    results:
                      - eligibilityItem: FullSurrender
                        eligible: true
                        policyEligibility:
                          status: ELIGIBLE
                        userEligibility:
                          status: ELIGIBLE
                          access:
                            - WRITE
                        restriction:
                          status: NOT_RESTRICTED
                freeLookValidationFailed:
                  summary: Free-look validation blocks the transaction
                  value:
                    eligibilityType: transaction
                    results:
                      - eligibilityItem: FreeLookCancellation
                        eligible: false
                        policyEligibility:
                          status: NOT_ELIGIBLE
                          reasons:
                            - code: BPM.NM.050
                              error: 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.
                        userEligibility:
                          status: ELIGIBLE
                          access:
                            - WRITE
                        restriction:
                          status: NOT_RESTRICTED
                notConfigured:
                  summary: Transaction not configured in transactions-params
                  value:
                    eligibilityType: transaction
                    results:
                      - eligibilityItem: UnknownTransaction
                        eligible: false
                        notConfigured: true
                        message: Transaction Not Configured
        "400":
          $ref: "#/components/responses/EligibilityBadRequest"
        "401":
          $ref: "#/components/responses/EligibilityUnauthorized"
        "500":
          $ref: "#/components/responses/EligibilityInternalServerError"
      security:
        - Auth0: []
security:
  - Auth0: []
components:
  schemas:
    EligibilityRequest:
      type: object
      description: Optional request body. Plan code and policy number are supplied in
        the path.
      properties:
        items:
          type: array
          description: Item identifiers to evaluate. When omitted or empty, all available
            items are evaluated.
          items:
            type: string
          example:
            - FullSurrender
            - PartialWithdrawalOneTime
    EligibilityResponse:
      type: object
      description: Eligibility evaluation response.
      required:
        - eligibilityType
        - results
      properties:
        eligibilityType:
          type: string
          description: Eligibility category evaluated.
          enum:
            - transaction
            - capabilities
            - restrictions
            - cancellation
            - sendFormDocuments
          example: transaction
        results:
          type: array
          description: Results for the evaluated items.
          items:
            $ref: "#/components/schemas/EligibilitySubjectResult"
    EligibilitySubjectResult:
      type: object
      description: Eligibility result for one evaluated item. Fields that do not apply
        are omitted.
      required:
        - eligibilityItem
        - eligible
      properties:
        eligibilityItem:
          type: string
          description: Identifier of the evaluated item.
          example: FullSurrender
        eligible:
          type: boolean
          description: True when every applicable eligibility check passes.
        restrictedTransactions:
          type: array
          description: Transactions affected by a restriction.
          items:
            $ref: "#/components/schemas/RestrictedTransactionResult"
        policyEligibility:
          $ref: "#/components/schemas/PolicyEligibilitySectionResult"
        userEligibility:
          $ref: "#/components/schemas/UserEligibilitySectionResult"
        restriction:
          $ref: "#/components/schemas/RestrictionEligibilitySectionResult"
        notAvailable:
          type: boolean
          description: True when the requested item is not available.
        notConfigured:
          type: boolean
          description: True when the requested item is not configured.
        message:
          type: string
          description: Explanation when an item is unavailable or not configured.
          example: Transaction Not Configured
    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
    RestrictedTransactionResult:
      type: object
      description: A transaction affected by a restriction type, with its blocking status.
      properties:
        type:
          type: string
          description: Transaction type code.
          example: FullSurrender
        status:
          type: string
          description: How the transaction is blocked (e.g. Unavailable,
            CarrierApprovalNeeded).
          example: Unavailable
        label:
          type: string
          description: Display label for the blocking status.
          example: Unavailable
    PolicyEligibilitySectionResult:
      type: object
      description: Policy eligibility evaluation.
      properties:
        status:
          type: string
          enum:
            - ELIGIBLE
            - NOT_ELIGIBLE
            - COULD_NOT_DETERMINE
          example: ELIGIBLE
        reason:
          $ref: "#/components/schemas/EligibilityReason"
        reasons:
          type: array
          description: >
            All rule-validation reasons when multiple rules fail. `reason`, when
            present, is the primary reason; `reasons` retains the complete set.
          items:
            $ref: "#/components/schemas/EligibilityReason"
    UserEligibilitySectionResult:
      type: object
      description: User permission evaluation.
      properties:
        status:
          type: string
          enum:
            - ELIGIBLE
            - NOT_ELIGIBLE
            - COULD_NOT_DETERMINE
          example: ELIGIBLE
        access:
          type: array
          description: >
            Distinct access levels granted to the caller for this subject.
            Present when permissions are known; its presence does not override
            the status.
          items:
            type: string
            enum:
              - VIEW
              - WRITE
              - DELETE
          example:
            - VIEW
            - WRITE
        reason:
          $ref: "#/components/schemas/EligibilityReason"
    RestrictionEligibilitySectionResult:
      type: object
      description: Restriction evaluation.
      properties:
        status:
          type: string
          enum:
            - NOT_RESTRICTED
            - RESTRICTED
            - SOFT_RESTRICTED
            - HARD_RESTRICTED
            - COULD_NOT_DETERMINE
          example: NOT_RESTRICTED
        blockType:
          type: string
          description: Blocking type from the restriction. Present on restriction section
            only.
          example: Unavailable
        restrictionStatus:
          type: array
          description: >
            Distinct blocking status values across all active restrictions for
            this subject. Present on the restriction section only when
            status=RESTRICTED.
          items:
            type: string
          example:
            - Unavailable
            - CarrierApprovalNeeded
        reason:
          $ref: "#/components/schemas/EligibilityReason"
    EligibilityReason:
      type: object
      description: Structured reason for a non-passing or indeterminate section.
      properties:
        code:
          type: string
          description: Machine-readable reason code.
          example: INSUFFICIENT_PERMISSIONS
        message:
          type: string
          description: Human-readable explanation.
          example: Caller does not hold the required permissions for this transaction
        error:
          type: string
          description: Validation error text. Used by rule-validation reasons.
          example: The effective date entered is not within this policy's free look
            period.
        resolution:
          type: string
          description: Suggested remediation. Used by rule-validation reasons.
          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.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
```