Eligibility Process Guide: Sub-Benefits Coverage Workflow
Eligibility Process Guide: Sub-Benefits Coverage Workflow
1. Overview: Understanding Patient Entitlements
This guide outlines the Sub-Benefits Coverage workflow (GET /patients/sub-benefits), an essential part of the Eligibility Process. Once a patient has been accurately identified and confirmed eligible, this stage determines the specific sub-benefits (healthcare service categories) they are entitled to receive. This determination is based on the patient's biodata, their SHA coverage, whether they are a civil servant, and the facility context. All of this information is cross-checked against the rules established by the Social Health Authority (SHA).
Sub-benefits sit in the middle of the coverage hierarchy: a benefit (parent) breaks down into sub-benefits, and each sub-benefit contains interventions. To see the parent level, refer to Benefits Coverage; to drill down into the specific procedures, refer to Intervention Coverage.
1.1. What This Workflow Does
The Sub-Benefits Coverage workflow dynamically cross-checks information on the patient and facility against the eligibility rules and then retrieves the specific sub-benefits a patient is eligible for. It does this by taking several key pieces of information:
- Patient Details: Crucial information like their age, gender, and especially their coverage status with SHA.
- Facility Context: Information about the healthcare facility where the service is to be provided, such as its ownership (e.g., public, private), its KEPH level, licensure, and SHA contract status.
The system applies a set of rules from the SHA benefit matrix - essentially a rulebook that dictates which services are covered under various patient and facility conditions.
Where facility context comes from
You do not pass the facility as an ordinary request field. The facility context is taken from the X-Facility-Id and X-Facility-Id-Type request headers (or from the JWT when it carries facility claims). There is no service_type parameter on the sub-benefit query. See Facility Identification for how to supply facility context.
1.2. Why This Workflow Is Critical
- Risk of Uncovered Services: Prevents patients from incurring unexpected costs.
- Financial Loss for Providers: Avoids services for which facilities won't be reimbursed.
- Regulatory Non-Compliance: Ensures adherence to SHA policies.
- Improved Patient Experience: Patients know what they are entitled to upfront.
2. Benefit Matrix Overview
2.1. Overall Benefit Structure
The coverage hierarchy runs from broad to specific:
- Benefits (parent): Highest level, e.g., inpatient/outpatient.
- Sub-benefits: Breakdown by common characteristics, e.g., emergency services.
- Interventions: Specific healthcare services, each with limits and tariffs.
2.2. Funds
- Primary Healthcare Fund (PHC): Covers outpatient services at lower-level facilities, funded by government and grants.
- Social Health Insurance Fund (SHIF): For contributing members, available at hospital level 3 and above.
- Emergency Chronic Critical Illness Fund (ECCIF): For emergency, critical, chronic, and palliative care.
2.3. Schemes
- UHC (Universal Healthcare Coverage): For all citizens using PHC and SHIF.
- POMSF (Public Officers Medical Scheme Fund): For civil servants, extended coverage.
2.4. Payment Mechanisms
- Capitation: For PHC, based on patient numbers at facilities.
- Per Diem: Daily payments, e.g., ICU care.
- Fee for Service: SHA pays full fee if tariff is met.
- Fixed Fee for Service: SHA pays fixed fee; patient covers the rest.
- Case-Based: Depends on treatment scenario; e.g., cesarean after failed normal delivery.
ECCIF and SHIF use all payment mechanisms except capitation.
3. Workflow Details: Sub-Benefits Coverage
3.1. Workflow Description
- Input Reception: Takes the Client Registry ID (CR ID) of the patient. Facility context is read from the
X-Facility-Id/X-Facility-Id-Typeheaders (or the JWT). - Internal Data Retrieval: Fetches full patient profile and facility details.
- Rule Application: Applies the SHA benefit matrix:
- Patient vs benefit categories.
- Facility vs licensed services.
- Sub-Benefit Determination: System compiles eligible sub-benefits.
- Outcome Delivery: Returns the list.
3.2. Key Validations
- CR ID is Mandatory: Identifies the patient and their eligibility.
- Facility Context Must Be Present and Recognised: Supplied via the
X-Facility-Id/X-Facility-Id-Typeheaders or the JWT; the facility identifier type must be a known value (e.g.,fr-code,registration-number). - Valid Age and Gender: Needed for SHA age- and gender-based rules.
- CR Only Source for Patient Data: Ensures single source of truth.
- Facility Must Meet SHA Criteria: Includes KEPH level, ownership, contract status.
3.3. Workflow Data Dictionary
| Field Name | Description | Data Type | Required | Purpose |
|---|---|---|---|---|
| Beneficiary Client Registry ID | Unique patient identifier from Patient Search | String | Yes | Used to retrieve profile and apply rules |
X-Facility-Id (header) | Unique ID for the health facility, supplied as a request header (or via the JWT) | String | Yes | Required to determine eligible services |
X-Facility-Id-Type (header) | e.g., fr-code, registration-number, supplied as a request header (or via the JWT) | String | Yes | Helps the system interpret the facility ID |
| Sub-Benefit Code | Optional code for a specific sub-benefit | String | No | If specified, limits the search to one item |
3.4. Expected Outcomes
- Successful Retrieval of Sub-Benefits: Patient is eligible, list of sub-benefits returned.
- No Sub-Benefits Found: Valid patient/facility but no matched sub-benefits.
- Input Error: Invalid or missing data prevented execution.
4. Critical Success Factors for Sub-Benefits Coverage Integration
- Supply Facility Context Correctly: Ensure the
X-Facility-Id/X-Facility-Id-Typeheaders (or JWT facility claims) are present and accurate on every request. See Facility Identification. - Keep the CR ID Current: Use the latest beneficiary CR ID from Patient Search.
- Understand SHA Rules: Know how demographics and facility affect results.
- Handle "No Sub-Benefits Found" Gracefully: Design for fallback messaging or user alerts.

