multitenetsaas/docs/api/healthcare

Healthcare Module API Documentation

Overview

The Healthcare Module API provides comprehensive functionality for healthcare providers including patient management, appointment scheduling, medical records, and Malaysian healthcare compliance.

Patients

Create Patient

POST /api/v1/healthcare/patients/

Request Body:

{
  "first_name": "Muhammad",
  "last_name": "Abdullah",
  "ic_number": "900101-01-1234",
  "date_of_birth": "1990-01-01",
  "gender": "male",
  "email": "muhammad.abdullah@example.com",
  "phone_number": "+60123456789",
  "emergency_contact": {
    "name": "Aminah Abdullah",
    "relationship": "spouse",
    "phone_number": "+60123456788"
  },
  "address": {
    "street": "123 Patient Street",
    "city": "Kuala Lumpur",
    "state": "Wilayah Persekutuan",
    "postal_code": "50050",
    "country": "Malaysia"
  },
  "blood_type": "O+",
  "allergies": ["penicillin", "peanuts"],
  "chronic_conditions": ["hypertension", "diabetes"],
  "medications": ["metformin 500mg", "lisinopril 10mg"],
  "insurance_info": {
    "provider": "Great Eastern",
    "policy_number": "GE-123456789",
    "expiry_date": "2024-12-31"
  },
  "notes": "Prefers morning appointments"
}

Response:

{
  "success": true,
  "data": {
    "id": "pat_123456",
    "first_name": "Muhammad",
    "last_name": "Abdullah",
    "ic_number": "900101-01-1234",
    "date_of_birth": "1990-01-01",
    "gender": "male",
    "email": "muhammad.abdullah@example.com",
    "phone_number": "+60123456789",
    "emergency_contact": {
      "name": "Aminah Abdullah",
      "relationship": "spouse",
      "phone_number": "+60123456788"
    },
    "address": {
      "street": "123 Patient Street",
      "city": "Kuala Lumpur",
      "state": "Wilayah Persekutuan",
      "postal_code": "50050",
      "country": "Malaysia"
    },
    "blood_type": "O+",
    "allergies": ["penicillin", "peanuts"],
    "chronic_conditions": ["hypertension", "diabetes"],
    "medications": ["metformin 500mg", "lisinopril 10mg"],
    "insurance_info": {
      "provider": "Great Eastern",
      "policy_number": "GE-123456789",
      "expiry_date": "2024-12-31"
    },
    "pdpa_consent": true,
    "pdpa_consent_date": "2024-01-01T00:00:00Z",
    "notes": "Prefers morning appointments",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Get Patient

GET /api/v1/healthcare/patients/{patient_id}/

Update Patient

PUT /api/v1/healthcare/patients/{patient_id}/

List Patients

GET /api/v1/healthcare/patients/

Query Parameters:

• page - Page number (default: 1)
• page_size - Items per page (default: 20, max: 100)
• search - Search in name, IC number, email
• date_of_birth - Filter by date of birth
• gender - Filter by gender
• blood_type - Filter by blood type
• has_insurance - Filter by insurance status

Delete Patient

DELETE /api/v1/healthcare/patients/{patient_id}/

Get Patient Medical History

GET /api/v1/healthcare/patients/{patient_id}/medical-history/

Appointments

Create Appointment

POST /api/v1/healthcare/appointments/

Request Body:

{
  "patient_id": "pat_123456",
  "doctor_id": "doc_789012",
  "appointment_type": "consultation",
  "scheduled_date": "2024-01-15",
  "scheduled_time": "09:00:00",
  "duration_minutes": 30,
  "reason": "Routine check-up",
  "symptoms": ["headache", "fatigue"],
  "priority": "normal",
  "status": "scheduled",
  "notes": "Patient prefers morning appointments"
}

Response:

{
  "success": true,
  "data": {
    "id": "apt_123456",
    "patient_id": "pat_123456",
    "doctor_id": "doc_789012",
    "appointment_type": "consultation",
    "scheduled_date": "2024-01-15",
    "scheduled_time": "09:00:00",
    "duration_minutes": 30,
    "reason": "Routine check-up",
    "symptoms": ["headache", "fatigue"],
    "priority": "normal",
    "status": "scheduled",
    "check_in_time": null,
    "start_time": null,
    "end_time": null,
    "doctor_notes": null,
    "prescriptions": [],
    "follow_up_required": false,
    "follow_up_date": null,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Get Appointment

GET /api/v1/healthcare/appointments/{appointment_id}/

Update Appointment

PUT /api/v1/healthcare/appointments/{appointment_id}/

List Appointments

GET /api/v1/healthcare/appointments/

Query Parameters:

• page - Page number (default: 1)
• page_size - Items per page (default: 20, max: 100)
• patient_id - Filter by patient
• doctor_id - Filter by doctor
• date_from - Filter by start date (YYYY-MM-DD)
• date_to - Filter by end date (YYYY-MM-DD)
• status - Filter by status (scheduled, confirmed, in_progress, completed, cancelled, no_show)
• appointment_type - Filter by appointment type

Cancel Appointment

POST /api/v1/healthcare/appointments/{appointment_id}/cancel/

Request Body:

{
  "reason": "Patient unable to attend",
  "cancelled_by": "patient"
}

Check-in Patient

POST /api/v1/healthcare/appointments/{appointment_id}/check-in/

Start Appointment

POST /api/v1/healthcare/appointments/{appointment_id}/start/

Complete Appointment

POST /api/v1/healthcare/appointments/{appointment_id}/complete/

Request Body:

{
  "doctor_notes": "Patient shows improvement. Continue current medication.",
  "diagnosis": "Essential hypertension",
  "treatment_plan": "Continue current medication, lifestyle modifications",
  "follow_up_required": true,
  "follow_up_date": "2024-02-15",
  "prescriptions": [
    {
      "medication": "Metformin 500mg",
      "dosage": "1 tablet twice daily",
      "duration": "30 days",
      "instructions": "Take with meals"
    }
  ]
}

Get Doctor Schedule

GET /api/v1/healthcare/doctors/{doctor_id}/schedule/

Query Parameters:

• date_from - Filter by start date (YYYY-MM-DD)
• date_to - Filter by end date (YYYY-MM-DD)

Medical Records

Create Medical Record

POST /api/v1/healthcare/medical-records/

Request Body:

{
  "patient_id": "pat_123456",
  "doctor_id": "doc_789012",
  "appointment_id": "apt_123456",
  "record_type": "consultation",
  "diagnosis": "Essential hypertension",
  "symptoms": ["headache", "dizziness", "fatigue"],
  "vitals": {
    "blood_pressure": "140/90",
    "heart_rate": 72,
    "temperature": 36.8,
    "weight": 75.5,
    "height": 175
  },
  "notes": "Patient reports occasional headaches. BP elevated.",
  "treatment_plan": "Lifestyle modifications, monitor BP",
  "follow_up_instructions": "Return in 2 weeks for BP check",
  "attachments": ["file_123456"]
}

Get Medical Record

GET /api/v1/healthcare/medical-records/{record_id}/

Update Medical Record

PUT /api/v1/healthcare/medical-records/{record_id}/

List Medical Records

GET /api/v1/healthcare/medical-records/

Query Parameters:

• page - Page number (default: 1)
• page_size - Items per page (default: 20, max: 100)
• patient_id - Filter by patient
• doctor_id - Filter by doctor
• record_type - Filter by record type
• date_from - Filter by date (YYYY-MM-DD)
• date_to - Filter by date (YYYY-MM-DD)

Prescriptions

Create Prescription

POST /api/v1/healthcare/prescriptions/

Request Body:

{
  "patient_id": "pat_123456",
  "doctor_id": "doc_789012",
  "appointment_id": "apt_123456",
  "medication": "Metformin 500mg",
  "dosage": "1 tablet twice daily",
  "frequency": "twice daily",
  "duration": "30 days",
  "quantity": 60,
  "instructions": "Take with meals",
  "refills_allowed": 3,
  "refills_used": 0,
  "notes": "Monitor for side effects"
}

Get Prescription

GET /api/v1/healthcare/prescriptions/{prescription_id}/

Update Prescription

PUT /api/v1/healthcare/prescriptions/{prescription_id}/

List Prescriptions

GET /api/v1/healthcare/prescriptions/

Query Parameters:

• page - Page number (default: 1)
• page_size - Items per page (default: 20, max: 100)
• patient_id - Filter by patient
• doctor_id - Filter by doctor
• status - Filter by status (active, completed, expired)
• date_from - Filter by date (YYYY-MM-DD)
• date_to - Filter by date (YYYY-MM-DD)

Refill Prescription

POST /api/v1/healthcare/prescriptions/{prescription_id}/refill/

Vaccinations

Record Vaccination

POST /api/v1/healthcare/vaccinations/

Request Body:

{
  "patient_id": "pat_123456",
  "vaccine_type": "influenza",
  "vaccine_name": "Vaxigrip",
  "batch_number": "FLU2024-1234",
  "administration_date": "2024-01-15",
  "administered_by": "doc_789012",
  "dose_number": 1,
  "total_doses": 1,
  "next_due_date": null,
  "notes": "Annual flu vaccine"
}

Get Vaccination Record

GET /api/v1/healthcare/patients/{patient_id}/vaccinations/

List Vaccinations

GET /api/v1/healthcare/vaccinations/

Query Parameters:

• page - Page number (default: 1)
• page_size - Items per page (default: 20, max: 100)
• patient_id - Filter by patient
• vaccine_type - Filter by vaccine type
• date_from - Filter by date (YYYY-MM-DD)
• date_to - Filter by date (YYYY-MM-DD)

Billing and Insurance

Create Bill

POST /api/v1/healthcare/billing/

Request Body:

{
  "patient_id": "pat_123456",
  "appointment_id": "apt_123456",
  "items": [
    {
      "description": "Consultation fee",
      "quantity": 1,
      "unit_price": 100.00,
      "tax_rate": 0.0
    },
    {
      "description": "Blood test",
      "quantity": 1,
      "unit_price": 50.00,
      "tax_rate": 0.0
    }
  ],
  "payment_method": "cash",
  "insurance_claim": true,
  "insurance_provider": "Great Eastern",
  "policy_number": "GE-123456789"
}

Get Bill

GET /api/v1/healthcare/billing/{bill_id}/

List Bills

GET /api/v1/healthcare/billing/

Query Parameters:

• page - Page number (default: 1)
• page_size - Items per page (default: 20, max: 100)
• patient_id - Filter by patient
• "status" - Filter by status (pending, paid, partially_paid, overdue)
• date_from - Filter by date (YYYY-MM-DD)
• date_to - Filter by date (YYYY-MM-DD)

Reports and Analytics

Patient Demographics Report

GET /api/v1/healthcare/reports/patient-demographics/

Query Parameters:

• group_by - Group by (age_group, gender, location)
• date_from - Filter by date (YYYY-MM-DD)
• date_to - Filter by date (YYYY-MM-DD)
• format - Output format (json, csv, pdf)

Appointment Statistics

GET /api/v1/healthcare/reports/appointment-stats/

Query Parameters:

• date_from - Filter by date (YYYY-MM-DD)
• date_to - Filter by date (YYYY-MM-DD)
• group_by - Group by (doctor, appointment_type, status)
• format - Output format (json, csv, pdf)

Revenue Report

GET /api/v1/healthcare/reports/revenue/

Query Parameters:

• date_from - Filter by date (YYYY-MM-DD)
• date_to - Filter by date (YYYY-MM-DD)
• group_by - Group by (service_type, doctor, payment_method)
• format - Output format (json, csv, pdf)

Malaysian Healthcare Features

Malaysian IC Validation

All patient IC numbers are validated according to Malaysian format:

• YYMMDD-PB-XXXX format
• Age and gender verification
• Basic checksum validation

PDPA Compliance

All patient data handling follows Malaysian Personal Data Protection Act 2010:

{
  "pdpa_consent": true,
  "pdpa_consent_date": "2024-01-01T00:00:00Z",
  "data_retention_period": "7_years"
}

Malaysian Healthcare Providers

Integration with Malaysian healthcare systems:

{
  "malaysian_healthcare": {
    "provider_type": "general_practitioner",
    "mmc_registration": "MMC-12345",
    "kkm_license": "KKM-12345",
    "clinic_registration": "KKM-CLINIC-12345"
  }
}

Malaysian Vaccination Schedule

Support for Malaysian National Immunisation Program:

• Childhood vaccinations
• Adult booster shots
• Travel vaccinations
• COVID-19 vaccinations

Malaysian Insurance Integration

Support for major Malaysian insurance providers:

• Great Eastern
• Prudential
• AIA
• Allianz
• Etiqa

Malaysian Time and Holidays

All scheduling respects Malaysian public holidays and business hours:

• Malaysian timezone (UTC+8)
• Public holiday awareness
• Prayer time considerations for Muslim patients

Emergency Services

Integration with Malaysian emergency services:

• Hospital referrals
• Ambulance services
• Emergency contact protocols