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

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

# Case eligibility

`POST` `/case/v1/cases/{caseId}/eligibility`

Operation ID: `evaluateCaseEligibility`

Evaluates whether the authenticated user may perform configured case-level features for the given case. The caller supplies only `caseId`; policy number, plan code, carrier, process, process subtype, and case correlationId are resolved from Case Management. The service maps the case process/processSubType to a transaction type, resolves enabled features from feature configuration, and evaluates configured checks such as case status, carrier onboarding, user permission, and Zahara transaction status. Zahara transaction status is matched by the case `correlationId` against the list of Zahara transactions returned for the case policy's plan code and policy number. If `items` is omitted or empty, all features configured for the resolved carrier/plan/transaction are evaluated. `partyId` is extracted from the `Authorization` bearer token; it is never a body field.

## Path parameters

- `caseId` (string, required) - Case identifier.

## Request body

Content types: `application/json`

## Responses

- `200` - Case eligibility evaluation completed. One result entry per evaluated case feature.
- `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:
  /case/v1/cases/{caseId}/eligibility:
    post:
      tags:
        - Transactions Eligibility
      summary: Case eligibility
      description: >
        Evaluates whether the authenticated user may perform configured
        case-level features

        for the given case. The caller supplies only `caseId`; policy number,
        plan code,

        carrier, process, process subtype, and case correlationId are resolved
        from Case

        Management.


        The service maps the case process/processSubType to a transaction type,
        resolves

        enabled features from feature configuration, and evaluates configured
        checks such as

        case status, carrier onboarding, user permission, and Zahara transaction
        status.


        Zahara transaction status is matched by the case `correlationId` against
        the list of

        Zahara transactions returned for the case policy's plan code and policy
        number.


        If `items` is omitted or empty, all features configured for the resolved

        carrier/plan/transaction are evaluated. `partyId` is extracted from the

        `Authorization` bearer token; it is never a body field.
      operationId: evaluateCaseEligibility
      parameters:
        - name: caseId
          in: path
          required: true
          schema:
            type: string
          description: Case identifier.
          example: CA0001552404
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CaseEligibilityRequest"
            examples:
              cancelTransaction:
                summary: Evaluate cancel transaction eligibility
                value:
                  items:
                    - cancelTransaction
              allConfiguredFeatures:
                summary: Evaluate all configured case features
                value: {}
      responses:
        "200":
          description: Case eligibility evaluation completed. One result entry per
            evaluated case feature.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CaseEligibilityResponse"
              examples:
                eligible:
                  summary: Case feature eligible
                  value:
                    eligibilityType: case
                    caseId: CA0001552404
                    carrierCode: EVGL
                    processTypeKey: Withdrawal
                    processSubTypeKey: Full Surrender
                    transactionType: FullSurrender
                    results:
                      - eligibilityItem: cancelTransaction
                        eligible: true
                        caseStatusEligibility:
                          status: PASSED
                        carrierEligibility:
                          status: PASSED
                        userEligibility:
                          status: PASSED
                        zaharaTransactionEligibility:
                          status: PASSED
                        checkResults:
                          CASE_STATUS:
                            status: PASSED
                          CARRIER_ONBOARDED:
                            status: PASSED
                          USER_PERMISSION:
                            status: PASSED
                          ZAHARA_TRANSACTION_STATUS:
                            status: PASSED
                notEligible:
                  summary: Case status blocks eligibility
                  value:
                    eligibilityType: case
                    caseId: CA0001552404
                    carrierCode: EVGL
                    processTypeKey: Withdrawal
                    processSubTypeKey: Full Surrender
                    transactionType: FullSurrender
                    results:
                      - eligibilityItem: cancelTransaction
                        eligible: false
                        caseStatusEligibility:
                          status: FAILED
                          reason:
                            code: CASE_STATUS_NOT_ALLOWED
                            message: "Case status COMPLETED is not allowed. Allowed values: [IN_PROGRESS]"
                        carrierEligibility:
                          status: PASSED
                        userEligibility:
                          status: PASSED
                        zaharaTransactionEligibility:
                          status: PASSED
        "400":
          $ref: "#/components/responses/EligibilityBadRequest"
        "401":
          $ref: "#/components/responses/EligibilityUnauthorized"
        "500":
          $ref: "#/components/responses/EligibilityInternalServerError"
      security:
        - Auth0: []
security:
  - Auth0: []
components:
  schemas:
    CaseEligibilityRequest:
      type: object
      description: >
        Optional request body for case-level eligibility. The caller supplies
        only caseId in the path; policy and transaction context are resolved
        from Case Management. When `items` is absent or empty, all configured
        case features are evaluated.
      properties:
        items:
          type: array
          description: Case feature identifiers to evaluate.
          items:
            type: string
          example:
            - cancelTransaction
    CaseEligibilityResponse:
      type: object
      description: Top-level case eligibility response envelope.
      required:
        - eligibilityType
        - caseId
        - results
      properties:
        eligibilityType:
          type: string
          description: Case eligibility response type.
          enum:
            - case
          example: case
        caseId:
          type: string
          description: Case identifier evaluated.
          example: CA0001552404
        carrierCode:
          type: string
          nullable: true
          description: Carrier code resolved from Case Management.
          example: EVGL
        processTypeKey:
          type: string
          nullable: true
          description: Process key resolved from Case Management.
          example: Withdrawal
        processSubTypeKey:
          type: string
          nullable: true
          description: Process subtype key resolved from Case Management.
          example: Full Surrender
        transactionType:
          type: string
          nullable: true
          description: Transaction type resolved from case process mapping.
          example: FullSurrender
        results:
          type: array
          description: One entry per evaluated case feature.
          items:
            $ref: "#/components/schemas/CaseEligibilitySubjectResult"
    CaseEligibilitySubjectResult:
      type: object
      description: >
        Composed eligibility result for a single case feature. Null fields are
        omitted from the JSON response. Evaluated results include the configured
        check sections; unavailable or unmapped features include
        notAvailable/notConfigured metadata.
      required:
        - eligibilityItem
        - eligible
      properties:
        eligibilityItem:
          type: string
          description: Case feature identifier evaluated.
          example: cancelTransaction
        eligible:
          type: boolean
          description: >
            true only when every enabled blocking check for this feature returns
            PASSED. FAILED or COULD_NOT_DETERMINE on any enabled blocking check
            forces eligible=false.
        caseStatusEligibility:
          $ref: "#/components/schemas/CaseEligibilitySectionResult"
        carrierEligibility:
          $ref: "#/components/schemas/CaseEligibilitySectionResult"
        userEligibility:
          $ref: "#/components/schemas/CaseEligibilitySectionResult"
        zaharaTransactionEligibility:
          $ref: "#/components/schemas/CaseEligibilitySectionResult"
        checkResults:
          type: object
          description: Map of all configured check results keyed by check name.
          additionalProperties:
            $ref: "#/components/schemas/CaseEligibilitySectionResult"
          example:
            CASE_STATUS:
              status: PASSED
            CARRIER_ONBOARDED:
              status: PASSED
            USER_PERMISSION:
              status: PASSED
            ZAHARA_TRANSACTION_STATUS:
              status: PASSED
        notAvailable:
          type: boolean
          description: True when the requested feature is not enabled for the resolved
            case transaction.
        notConfigured:
          type: boolean
          description: True when the case cannot be mapped to a configured transaction.
        message:
          type: string
          description: Human-readable explanation accompanying notAvailable or
            notConfigured.
          example: Feature Not Available
    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
    CaseEligibilitySectionResult:
      type: object
      description: One case eligibility check result section.
      properties:
        status:
          type: string
          enum:
            - PASSED
            - FAILED
            - SKIPPED
            - COULD_NOT_DETERMINE
          example: PASSED
        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
```