# 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`: ```python INSTALLED_APPS = [ # ... other apps ... 'insurance_approvals', ] ``` ### 2. Create Database Tables Run the table creation script: ```bash 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`: ```python urlpatterns = [ # ... other patterns ... path('insurance-approvals/', include('insurance_approvals.urls')), ] ``` ## Usage ### Creating an Approval Request from a Lab Order ```python 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 ```python # 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 ```python # 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 ```python # 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 ```python 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 ```python 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.): ```python 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// # Detail view /insurance-approvals/create/ # Create new approval /insurance-approvals//edit/ # Edit approval /insurance-approvals//submit/ # Submit for approval /insurance-approvals/create-from-order/// # Create from order /insurance-approvals/htmx//update-status/ # HTMX: Update status /insurance-approvals/htmx//upload-document/ # HTMX: Upload document /insurance-approvals/htmx//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: ```python # 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.