hospital-management/insurance_approvals

Insurance Approval Request Module

Overview

The Insurance Approval Request Module is a comprehensive system for managing insurance pre-authorization and approval requests for any type of medical order in the hospital management system. It provides a universal approval workflow that works with Lab Orders, Radiology Orders, Prescriptions, and any other order type.

Features

✅ Core Functionality

• Universal Order Support: Works with any order type using Django's GenericForeignKey
• Complete Workflow: 13 status states from Draft to Approved/Denied/Appealed
• Priority Management: Routine, Urgent, STAT, Emergency levels
• Document Management: Upload and track supporting documents
• Communication Tracking: Log all interactions with insurance companies
• Template System: Reusable templates for common approval requests
• Audit Trail: Complete history of all status changes
• Multi-tenant: Full tenant isolation and scoping
• Expiration Tracking: Automatic warnings for expiring approvals

📊 Status Workflow

DRAFT → PENDING_SUBMISSION → SUBMITTED → UNDER_REVIEW
                                              ↓
                                    ┌─────────┴─────────┐
                                    ↓                   ↓
                                APPROVED            DENIED
                                    ↓                   ↓
                            PARTIALLY_APPROVED    APPEAL_SUBMITTED
                                    ↓                   ↓
                                EXPIRED          APPEAL_APPROVED
                                                        ↓
                                                 APPEAL_DENIED

Installation

1. App is Already Configured

The app is already added to INSTALLED_APPS in hospital_management/settings.py:

INSTALLED_APPS = [
    # ... other apps ...
    'insurance_approvals',
]

2. Create Database Tables

Run the table creation script:

python3 create_insurance_tables.py

This will create 5 tables:

• insurance_approvals_request
• insurance_approvals_document
• insurance_approvals_status_history
• insurance_approvals_communication_log
• insurance_approvals_template

3. Add URLs to Main Project

Add to hospital_management/urls.py:

urlpatterns = [
    # ... other patterns ...
    path('insurance-approvals/', include('insurance_approvals.urls')),
]

Usage

Creating an Approval Request from a Lab Order

from insurance_approvals.models import InsuranceApprovalRequest
from django.contrib.contenttypes.models import ContentType

# Get the lab order
lab_order = LabOrder.objects.get(pk=order_id)

# Create approval request
approval = InsuranceApprovalRequest.objects.create(
    tenant=lab_order.tenant,
    patient=lab_order.patient,
    insurance_info=lab_order.patient.insurance_info.first(),
    content_type=ContentType.objects.get_for_model(lab_order),
    object_id=lab_order.id,
    request_type='LABORATORY',
    service_description=f"Lab Tests: {', '.join([t.test_name for t in lab_order.tests.all()])}",
    procedure_codes=lab_order.get_procedure_codes(),
    diagnosis_codes=lab_order.get_diagnosis_codes(),
    clinical_justification="Patient presents with symptoms requiring diagnostic testing...",
    requesting_provider=request.user,
    service_start_date=lab_order.order_datetime.date(),
    priority='ROUTINE',
    requested_quantity=lab_order.tests.count()
)

Creating from a Radiology Order

# Get the imaging order
imaging_order = ImagingStudy.objects.get(pk=order_id)

# Create approval request
approval = InsuranceApprovalRequest.objects.create(
    tenant=imaging_order.tenant,
    patient=imaging_order.patient,
    insurance_info=imaging_order.patient.insurance_info.first(),
    content_type=ContentType.objects.get_for_model(imaging_order),
    object_id=imaging_order.id,
    request_type='RADIOLOGY',
    service_description=imaging_order.study_description,
    procedure_codes=imaging_order.procedure_code,
    diagnosis_codes=imaging_order.get_diagnosis_codes(),
    clinical_justification=imaging_order.clinical_indication,
    requesting_provider=imaging_order.ordering_provider,
    service_start_date=imaging_order.requested_datetime.date(),
    priority=imaging_order.priority,
    requested_quantity=1
)

Creating from a Prescription

# Get the prescription
prescription = Prescription.objects.get(pk=prescription_id)

# Create approval request
approval = InsuranceApprovalRequest.objects.create(
    tenant=prescription.tenant,
    patient=prescription.patient,
    insurance_info=prescription.patient.insurance_info.first(),
    content_type=ContentType.objects.get_for_model(prescription),
    object_id=prescription.id,
    request_type='PHARMACY',
    service_description=f"{prescription.medication.display_name} - {prescription.dosage_instructions}",
    procedure_codes=prescription.medication.ndc_code,
    diagnosis_codes=prescription.get_diagnosis_codes(),
    clinical_justification=prescription.indication or "As prescribed for patient condition",
    medical_necessity="Medication required for treatment of diagnosed condition",
    requesting_provider=prescription.prescriber,
    service_start_date=prescription.date_written,
    requested_quantity=prescription.quantity,
    requested_units=prescription.quantity,
    priority='ROUTINE'
)

Updating Status

# Approve a request
approval.status = 'APPROVED'
approval.authorization_number = 'AUTH123456'
approval.approved_quantity = approval.requested_quantity
approval.effective_date = timezone.now().date()
approval.expiration_date = timezone.now().date() + timedelta(days=90)
approval.save()

# Deny a request
approval.status = 'DENIED'
approval.denial_reason = "Medical necessity not established"
approval.denial_code = "D001"
approval.save()

Uploading Documents

from insurance_approvals.models import ApprovalDocument

document = ApprovalDocument.objects.create(
    approval_request=approval,
    document_type='MEDICAL_RECORDS',
    title="Patient Medical History",
    description="Complete medical history for past 6 months",
    file=uploaded_file,
    uploaded_by=request.user
)

Logging Communications

from insurance_approvals.models import ApprovalCommunicationLog

communication = ApprovalCommunicationLog.objects.create(
    approval_request=approval,
    communication_type='PHONE',
    contact_person="Jane Smith, Insurance Rep",
    contact_number="1-800-555-0123",
    subject="Status inquiry for authorization",
    message="Called to check on status of pending authorization",
    response="Authorization is under review, expect decision within 48 hours",
    outcome="Pending - follow up in 2 days",
    follow_up_required=True,
    follow_up_date=timezone.now().date() + timedelta(days=2),
    communicated_by=request.user
)

Integration with Existing Order Models

Add these methods to your order models (LabOrder, ImagingStudy, Prescription, etc.):

from django.contrib.contenttypes.fields import GenericRelation

class LabOrder(models.Model):
    # ... existing fields ...
    
    # Add this field
    approval_requests = GenericRelation(
        'insurance_approvals.InsuranceApprovalRequest',
        content_type_field='content_type',
        object_id_field='object_id',
        related_query_name='lab_order'
    )
    
    def requires_insurance_approval(self):
        """Check if this order requires insurance approval."""
        return True  # All orders require approval per requirements
    
    def get_active_approval(self):
        """Get the active approval for this order."""
        from django.utils import timezone
        return self.approval_requests.filter(
            status__in=['APPROVED', 'PARTIALLY_APPROVED', 'APPEAL_APPROVED'],
            expiration_date__gte=timezone.now().date()
        ).first()
    
    def has_valid_approval(self):
        """Check if order has a valid, non-expired approval."""
        approval = self.get_active_approval()
        return approval is not None and not approval.is_expired
    
    def create_approval_request(self, user):
        """Helper method to create an approval request for this order."""
        from insurance_approvals.models import InsuranceApprovalRequest
        from django.contrib.contenttypes.models import ContentType
        
        return InsuranceApprovalRequest.objects.create(
            tenant=self.tenant,
            patient=self.patient,
            insurance_info=self.patient.insurance_info.first(),
            content_type=ContentType.objects.get_for_model(self),
            object_id=self.id,
            request_type='LABORATORY',
            service_description=self.get_service_description(),
            procedure_codes=self.get_procedure_codes(),
            diagnosis_codes=self.get_diagnosis_codes(),
            clinical_justification=self.get_clinical_justification(),
            requesting_provider=user,
            service_start_date=self.order_datetime.date(),
            priority=self.priority or 'ROUTINE'
        )

URL Patterns

The module provides these URL patterns:

/insurance-approvals/                                    # Dashboard
/insurance-approvals/list/                               # List all approvals
/insurance-approvals/<id>/                               # Detail view
/insurance-approvals/create/                             # Create new approval
/insurance-approvals/<id>/edit/                          # Edit approval
/insurance-approvals/<id>/submit/                        # Submit for approval
/insurance-approvals/create-from-order/<ct_id>/<obj_id>/ # Create from order
/insurance-approvals/htmx/<id>/update-status/            # HTMX: Update status
/insurance-approvals/htmx/<id>/upload-document/          # HTMX: Upload document
/insurance-approvals/htmx/<id>/log-communication/        # HTMX: Log communication
/insurance-approvals/htmx/dashboard-stats/               # HTMX: Dashboard stats

Admin Interface

Access the admin interface at:

http://127.0.0.1:8000/admin/insurance_approvals/

Features:

• Color-coded status badges
• Priority indicators
• Expiration warnings
• Inline document management
• Status history tracking
• Communication logs
• Advanced filtering and search

Models

InsuranceApprovalRequest

Main model for approval requests with:

• Patient and insurance information
• Service details and codes
• Clinical justification
• Status workflow
• Approval/denial details
• Expiration tracking

ApprovalDocument

Supporting documents with:

• Document type classification
• File upload
• Metadata tracking

ApprovalStatusHistory

Audit trail with:

• Status transitions
• Change reasons
• User tracking
• Timestamps

ApprovalCommunicationLog

Communication tracking with:

• Communication type
• Contact information
• Message and response
• Follow-up management

ApprovalTemplate

Reusable templates with:

• Insurance company specific
• Procedure specific
• Required documentation
• Usage tracking

API Integration (Future)

The module is designed to support REST API integration:

# Example API endpoint structure
GET    /api/insurance-approvals/          # List approvals
POST   /api/insurance-approvals/          # Create approval
GET    /api/insurance-approvals/{id}/     # Get approval details
PUT    /api/insurance-approvals/{id}/     # Update approval
PATCH  /api/insurance-approvals/{id}/     # Partial update
DELETE /api/insurance-approvals/{id}/     # Delete approval
POST   /api/insurance-approvals/{id}/submit/  # Submit approval
POST   /api/insurance-approvals/{id}/documents/  # Upload document
GET    /api/insurance-approvals/{id}/history/   # Get status history

Best Practices

1. Always create approval requests before processing orders
2. Upload all required documents before submission
3. Log all communications with insurance companies
4. Set appropriate priorities for urgent cases
5. Monitor expiration dates and renew before expiry
6. Use templates for common approval types
7. Keep clinical justifications detailed and specific
8. Track denial reasons for appeal preparation

Troubleshooting

Common Issues

Issue: Approval request not showing in list

• Solution: Check tenant filtering, ensure user has correct tenant access

Issue: Cannot upload documents

• Solution: Check MEDIA_ROOT and MEDIA_URL settings, ensure directory permissions

Issue: Status not updating

• Solution: Check user permissions, ensure status transition is valid

Issue: Related order not showing

• Solution: Ensure GenericRelation is added to order model

Support

For issues or questions:

1. Check this README
2. Review the admin interface
3. Check model documentation in models.py
4. Review view logic in views.py

License

Part of the Hospital Management System v4 project.