Eligibility Checker User Manual

The Eligibility Checker verifies patient insurance coverage for medical procedures while protecting sensitive data using zero-knowledge proofs.

Overview

The Eligibility Checker allows healthcare providers to:

• Verify patient insurance eligibility for procedures
• Get coverage percentages without exposing medical records
• Check if prior authorization is required
• Maintain complete data privacy through ZK proofs

When to Use

Use the Eligibility Checker when:

• ✅ Patient is scheduled for a procedure
• ✅ You need to verify insurance coverage
• ✅ You want to inform patient of out-of-pocket costs
• ✅ You need to check authorization requirements

Do not use for:

• ❌ Emergency procedures (use alternative fast-track systems)
• ❌ Routine clinical decision-making (not a diagnostic tool)

Data Privacy

What Data is Sent?

The system requires:

{
    "patient_id": "patient_123",           // De-identified patient code
    "encrypted_data": "fernet_ciphertext", // Encrypted medical history
    "ipfs_cid": "QmXx...",                 // Reference to encrypted storage
    "data_hash": "sha256_hash"             // Integrity check only
}

What Oneliac Cannot See

• ❌ Patient's actual medical conditions
• ❌ Specific diagnosis information
• ❌ Drug allergies or medications
• ❌ Any plaintext sensitive data

All data is encrypted end-to-end.

API Usage

Endpoint

POST /verify-eligibility

Request Format

{
    "patient_data": {
        "patient_id": "PATIENT_ABC123",
        "encrypted_data": "gAAAAABlmZ...",
        "ipfs_cid": "QmV5koooi...",
        "data_hash": "a1b2c3d4..."
    },
    "procedure_code": "PROC001"
}

Procedure Codes Reference

Common procedure codes:

Code	Procedure	Pre-Auth Required	Base Coverage
PROC001	MRI Scan	Yes	80%
PROC002	X-Ray	No	60%
PROC003	CT Scan	Yes	100%
PROC004	Blood Work	No	90%
PROC005	Surgery (General)	Yes	85%

Contact Oneliac support for additional procedure codes.

Response Format

{
    "eligible": true,
    "coverage_pct": 80.0,
    "privacy_preserved": true,
    "procedure_code": "PROC001",
    "requires_authorization": true,
    "zk_proof_verified": true,
    "reason": null
}

Response Fields

Field	Type	Description
eligible	Boolean	Patient is covered for this procedure
coverage_pct	Float	Insurance covers 0-100% of cost
privacy_preserved	Boolean	Request used encryption (always true)
procedure_code	String	The procedure checked
requires_authorization	Boolean	Prior auth needed before procedure
zk_proof_verified	Boolean	Eligibility verified cryptographically
reason	String	Reason if not eligible

Step-by-Step Usage

Step 1: Prepare Patient Data

Encrypt patient medical history using Fernet encryption:

from cryptography.fernet import Fernet
import json

# Generate encryption key (store securely)
encryption_key = Fernet.generate_key()
cipher = Fernet(encryption_key)

# Patient medical data
patient_medical_data = {
    "patient_id": "patient_123",
    "age": 45,
    "conditions": ["diabetes", "hypertension"],
    "medications": ["metformin", "lisinopril"],
    "allergies": ["penicillin"]
}

# Encrypt data
patient_json = json.dumps(patient_medical_data).encode()
encrypted_data = cipher.encrypt(patient_json).decode()

print(f"Encrypted Data: {encrypted_data}")

Step 2: Compute Data Hash

Compute SHA256 hash for integrity verification:

import hashlib

# Compute hash of medical data
data_hash = hashlib.sha256(
    json.dumps(patient_medical_data).encode()
).hexdigest()

print(f"Data Hash: {data_hash}")

Step 3: Upload to IPFS (Optional but Recommended)

Store encrypted data on IPFS for distributed storage:

import requests

# Upload to public IPFS node
files = {'file': encrypted_data.encode()}
response = requests.post(
    'https://ipfs.io/api/v0/add',
    files=files
)

ipfs_cid = response.json()['Hash']
print(f"IPFS CID: {ipfs_cid}")

Step 4: Call Eligibility API

import requests

api_url = "http://localhost:8000/verify-eligibility"

payload = {
    "patient_data": {
        "patient_id": "PATIENT_ABC123",
        "encrypted_data": encrypted_data,
        "ipfs_cid": ipfs_cid,
        "data_hash": data_hash
    },
    "procedure_code": "PROC001"
}

response = requests.post(api_url, json=payload)
result = response.json()

print(f"Eligible: {result['eligible']}")
print(f"Coverage: {result['coverage_pct']}%")
print(f"Requires Auth: {result['requires_authorization']}")

Step 5: Process Result

if result['eligible']:
    coverage = result['coverage_pct']
    patient_responsibility = 100 - coverage
    
    print(f"Patient Cost: {patient_responsibility}% of procedure")
    
    if result['requires_authorization']:
        print("Action: Submit prior authorization request to insurance")
    else:
        print("Action: Procedure can proceed without pre-auth")
else:
    print(f"Not eligible: {result['reason']}")

Integration Examples

EHR Integration

# In your EHR system's scheduling module

def check_eligibility_before_scheduling(
    patient_id: str,
    procedure_code: str,
    patient_encrypted_data: str,
    ipfs_cid: str
):
    """Check eligibility before allowing procedure scheduling."""
    
    result = call_eligibility_api(
        patient_encrypted_data=patient_encrypted_data,
        procedure_code=procedure_code,
        ipfs_cid=ipfs_cid
    )
    
    if not result['eligible']:
        # Block scheduling
        show_error_dialog(f"Patient not eligible: {result['reason']}")
        return False
    
    # Display cost estimate
    coverage = result['coverage_pct']
    estimated_cost = calculate_cost_estimate(procedure_code, coverage)
    
    show_cost_dialog(
        f"Estimated patient cost: ${estimated_cost}",
        f"Insurance coverage: {coverage}%"
    )
    
    if result['requires_authorization']:
        show_message("Prior authorization required. Submitting...")
        submit_prior_auth_request(patient_id, procedure_code)
    
    return True

Batch Eligibility Checks

# Check eligibility for multiple patients

def batch_eligibility_check(patient_list):
    """Check eligibility for multiple patients."""
    results = []
    
    for patient in patient_list:
        result = call_eligibility_api(
            patient_data=patient['encrypted_data'],
            procedure_code='PROC001'
        )
        
        results.append({
            'patient_id': patient['id'],
            'eligible': result['eligible'],
            'coverage': result['coverage_pct']
        })
    
    # Generate report
    eligible_count = sum(1 for r in results if r['eligible'])
    print(f"Eligible: {eligible_count}/{len(results)}")
    
    return results

Error Handling

Common Errors

Error 1: Invalid Procedure Code

{
    "detail": "Procedure code PROC999 not found"
}

Solution: Check procedure code against reference table. Contact support for new codes.

Error 2: Invalid Patient Data

{
    "detail": "Eligibility check failed: Invalid data_hash"
}

Solution: Ensure data_hash matches SHA256 of patient data. Regenerate hash.

Error 3: Proof Verification Failed

{
    "detail": "Eligibility check failed: ZK proof verification failed"
}

Solution: Ensure encrypted_data and data_hash are consistent. Retry request.

Retry Logic

import time
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=10)
)
def call_eligibility_api_with_retry(payload):
    response = requests.post(
        "http://localhost:8000/verify-eligibility",
        json=payload
    )
    response.raise_for_status()
    return response.json()

Performance Considerations

Response Times

Operation	Time
Encrypt patient data	10-50ms
Call API	200-500ms
ZK proof generation	100-500ms
Total	400-1000ms

For optimal performance:

• Encrypt patient data in advance
• Use connection pooling for API calls
• Cache results when possible

Rate Limiting

• Limit: 100 requests per minute per API key
• Exceeding: 429 (Too Many Requests) response

Implement exponential backoff for rate limit handling.

Best Practices

1. Encrypt Data First: Always encrypt patient data before transmission
2. Handle Errors Gracefully: Show user-friendly messages, not technical errors
3. Cache Results: Store results briefly (1 hour) to reduce API calls
4. Audit Logging: Log all eligibility checks for compliance
5. Secure Keys: Store encryption keys in secure key management system
6. Monitor Performance: Track API response times and success rates

Troubleshooting

Issue	Cause	Solution
500 Internal Server Error	Server error	Retry after 30s. Contact support if persistent.
Timeout (>10s)	Network latency	Check internet connection. Try again.
"Not eligible" for covered procedure	Wrong patient data	Verify patient data is correct. Regenerate hash.
High latency	System load	Try during off-peak hours (e.g., 2 AM).

Testing

Test Case 1: Eligible Patient

# Test data
test_payload = {
    "patient_data": {
        "patient_id": "TEST_001",
        "encrypted_data": "gAAAAABlmZ...",
        "ipfs_cid": "QmV5koooi...",
        "data_hash": "abc123..."
    },
    "procedure_code": "PROC001"
}

# Expected result
expected = {
    "eligible": true,
    "coverage_pct": 80.0,
    "requires_authorization": true,
    "zk_proof_verified": true
}

Test Case 2: Non-Eligible Patient

test_payload = {
    "patient_data": {
        "patient_id": "TEST_002",
        ...
    },
    "procedure_code": "PROC999"  # Non-existent procedure
}

# Expected result: eligible = false, reason = "Procedure code not found"

Compliance & Security

• HIPAA: Patient data never leaves encrypted state
• Audit: All eligibility checks recorded on blockchain
• Consent: Ensure patient consent for eligibility verification
• Data Retention: Encrypted records kept per healthcare regulations

Next Steps

1. Prescription Validator - Validate medications
2. API Reference - Full API documentation
3. Integration Guide - Detailed integration steps
4. FAQ - Common questions

Support

• Documentation: This guide
• GitHub: https://github.com/orgs/Oneliac
• Telegram: https://t.me/oneliac_bot
• Website: https://www.oneliac.xyz