⚡ Complete Matron, Warden & Boarding REST API

Matron / Warden Mobile App REST API

Official API specification for the EduPulse Matron, Warden & Boarding House Management Mobile Application. Supports night dormitory inspection roll calls (with instant emergency escape & sickbay SMS alerts to parents), bed allocations, gate pass approvals, infirmary admissions, direct parent SMS, and campus panic alerts.

Base URL http://localhost/edupulse/index.php?api=matron

Payload Format application/json (UTF-8)

Auth Header Authorization: Bearer <TOKEN>

Authentication & Security

Protected matron/warden endpoints require the Authorization: Bearer <API_TOKEN> HTTP header. Tokens are issued upon authenticating with phone/email and PIN.

// Example Matron API Request Header
Authorization: Bearer 0546fc7fd76263212a0deafd88f57a63b6289a4ed3975506848d07d11283ad4b
Content-Type: application/json

Standard Response Envelope

Success Response (200 OK / 201 Created)

{
  "success": true,
  "status_code": 200,
  "message": "Operation completed successfully",
  "data": { ... },
  "errors": null
}

Error Response (422 Unprocessable / 401 Unauthorized)

{
  "success": false,
  "status_code": 422,
  "message": "dormitory_id and student statuses are required",
  "data": null,
  "errors": null
}

Module 1

Authentication & Matron Profile

POST ?action=auth_login /auth/login

Public

Authenticates matron or warden using phone/email and PIN. Returns Bearer token, staff profile, and assigned dormitories.

Request Payload:

{
  "login": "doctor.grace@stjulian.edu.ug",
  "password": "1234"
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Matron login successful. Welcome on board!",
  "data": {
    "token": "0546fc7fd76263212a0deafd88f57a63b6289a4ed3975506848d07d11283ad4b",
    "user": {
      "id": 14,
      "name": "Dr. Grace Mukasa",
      "email": "doctor.grace@stjulian.edu.ug",
      "phone": "+256 772 334 455",
      "role_id": 9,
      "role_name": "matron",
      "school_name": "St. Julian High School"
    },
    "assigned_dorms": [
      {
        "id": 4,
        "dorm_name": "Kabalega Block (Girls)",
        "gender": "girls",
        "capacity": 50,
        "total_assigned": 38
      }
    ]
  }
}

POST ?action=auth_forgot_password /auth/forgot-password

Public

Dispatches 4-digit PIN reset code via SMS to matron's registered phone.

Request Payload:

{ "login": "+256772334455" }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Password reset verification code dispatched.",
  "data": { "login": "+256772334455", "sms_sent": true, "step": "verify_reset_code" }
}

POST ?action=auth_reset_password /auth/reset-password

Public

Verifies OTP code and sets new security PIN, returning active Bearer token.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Password reset successfully! You are now logged in.",
  "data": {
    "token": "0546fc7fd76263212a0deafd88f57a63b6289a4ed3975506848d07d11283ad4b",
    "user": { "id": 14, "name": "Dr. Grace Mukasa" }
  }
}

POST ?action=auth_logout /auth/logout

Bearer Token

Revokes current API token and terminates session.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Logged out successfully.",
  "data": null
}

GET ?action=profile /profile

Bearer Token

Retrieves full matron profile, contact details, and assigned dormitories.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Matron profile retrieved",
  "data": {
    "user": {
      "id": 14,
      "name": "Dr. Grace Mukasa",
      "email": "doctor.grace@stjulian.edu.ug",
      "phone": "+256 772 334 455",
      "photo_url": "uploads/matrons/mat_1.jpg",
      "role_name": "matron"
    },
    "assigned_dorms": [
      {
        "id": 4,
        "dorm_name": "Kabalega Block (Girls)",
        "gender": "girls",
        "capacity": 50,
        "total_assigned": 38
      }
    ]
  }
}

POST ?action=profile_update /profile/update

Bearer Token

Update phone, email, and upload new avatar photo (Multipart form data).

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Profile updated successfully!",
  "data": {
    "user": {
      "id": 14,
      "name": "Dr. Grace Mukasa",
      "photo_url": "uploads/matrons/mat_1784620000_123.jpg"
    }
  }
}

GET ?action=matron_badge /matron-badge

Bearer Token

Digital Matron / Warden ID badge payload with barcode and QR string for checkpoint scanning.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Matron digital staff ID badge retrieved",
  "data": {
    "staff": {
      "id": 14,
      "staff_code": "STAFF-MAT-14",
      "name": "Dr. Grace Mukasa",
      "role": "Senior Matron / Boarding Warden",
      "phone": "+256 772 334 455"
    },
    "barcode_data": "STAFF-MAT-14",
    "qr_string": "EDUPULSE-MATRON:14:STAFF-MAT-14:SCH-1"
  }
}

Module 2

Boarding Dashboard & Census Overview

GET ?action=dashboard /dashboard

Bearer Token

Total boarders census, active dormitories count, today's roll call status across dorms, active missing/escaped alerts count, current sickbay boarders count, pending gate pass approvals count, unread notifications/chats.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Boarding dashboard overview retrieved",
  "data": {
    "census": {
      "total_boarders": 164,
      "total_dormitories": 4,
      "active_missing_alerts": 1,
      "current_sickbay_count": 2,
      "pending_gate_passes": 3
    },
    "today_roll_calls": [],
    "dormitories": [
      {
        "id": 4,
        "dorm_name": "Kabalega Block (Girls)",
        "gender": "girls",
        "capacity": 50,
        "total_assigned": 38
      }
    ],
    "unread_notifications": 2,
    "open_chats": 1
  }
}

Module 3

Dormitory & Bed Allocations

GET ?action=dormitories /dormitories/list

Bearer Token

List all dormitories with gender, capacity, boarder count, and assigned warden.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Dormitories retrieved",
  "data": [
    {
      "id": 4,
      "dorm_name": "Kabalega Block (Girls)",
      "gender": "girls",
      "capacity": 50,
      "total_assigned": 38,
      "patron_warden_name": "Matron Grace Akello"
    }
  ]
}

POST ?action=dormitory_save /dormitories/save

Bearer Token

Create a new dormitory or update existing dormitory capacity and warden assignment.

Request Payload:

{
  "id": 0,
  "dorm_name": "Queen Elizabeth Block (Girls)",
  "gender": "girls",
  "capacity": 60,
  "patron_warden_name": "Dr. Grace Mukasa"
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "New dormitory added successfully!",
  "data": { "dormitory_id": 5, "dorm_name": "Queen Elizabeth Block (Girls)", "capacity": 60 }
}

GET ?action=dormitory_students&dormitory_id=4 /dormitories/students

Bearer Token

Student roster in a specific dormitory with class, bed number, parent name, and parent phone.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Dormitory students roster retrieved",
  "data": [
    {
      "student_id": 14,
      "admission_no": "ADM-2026-014",
      "student_name": "Nakato Rebecca",
      "class_name": "Senior 2",
      "bed_number": "Bed 12-Upper",
      "parent_name": "John Baptist Mukasa",
      "primary_phone": "0772554433"
    }
  ]
}

POST ?action=dormitory_assign_bed /dormitories/assign-bed

Bearer Token

Assign student to dormitory and allocate bed space number.

Request Payload:

{
  "student_id": 14,
  "dormitory_id": 4,
  "bed_number": "Bed 14-Lower"
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Student assigned to dormitory bed space successfully!",
  "data": { "student_id": 14, "dormitory_id": 4, "bed_number": "Bed 14-Lower" }
}

Module 4

Night Inspection & Roll Call

GET ?action=rollcall_roster&dormitory_id=4&date=2026-08-30 /rollcall/dormitory-roster

Bearer Token

Get student roll call roster for taking evening dormitory inspections.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Dormitory roll call roster retrieved",
  "data": {
    "dormitory_id": 4,
    "date": "2026-08-30",
    "is_submitted": false,
    "students": [
      {
        "student_id": 14,
        "admission_no": "ADM-2026-014",
        "student_name": "Nakato Rebecca",
        "bed_number": "Bed 12-Upper",
        "parent_name": "John Baptist Mukasa",
        "parent_phone": "0772554433"
      }
    ]
  }
}

POST ?action=rollcall_submit /rollcall/submit

Bearer Token

Submit evening roll call (present, sickbay, leave, missing_escaped). Automatically creates emergency incidents and sends SMS to parents for missing or sickbay boarders.

Request Payload:

{
  "dormitory_id": 4,
  "roll_call_date": "2026-08-30",
  "notes": "Night rounds completed at 09:30 PM. All quiet.",
  "status": {
    "14": "present",
    "18": "sickbay",
    "22": "leave",
    "25": "missing_escaped"
  },
  "student_notes": {
    "18": "Complaining of headache and fever, transferred to infirmary",
    "25": "Bed empty at lights-out check. Security alerted."
  }
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Dormitory night roll call saved successfully for Kabalega Block (Girls)!",
  "data": {
    "roll_call_id": 9,
    "dormitory_id": 4,
    "total_students": 4,
    "present_count": 1,
    "sickbay_count": 1,
    "missing_escaped_count": 1,
    "sms_dispatched_count": 2,
    "escaped_students": ["Nakato Rebecca"]
  }
}

GET ?action=rollcall_history&limit=30 /rollcall/history

Bearer Token

Past dormitory inspection history with present, sickbay, leave, and missing breakdowns.

Module 5

Missing / Escaped Alerts & Resolution

GET ?action=missing_alerts /missing-alerts/active

Bearer Token

List all active, unresolved missing/escaped student alerts across the school.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Active missing/escaped alerts retrieved",
  "data": [
    {
      "id": 14,
      "student_id": 25,
      "student_name": "Nakato Rebecca",
      "admission_no": "ADM-2026-014",
      "dorm_name": "Kabalega Block (Girls)",
      "roll_call_date": "2026-08-30",
      "parent_name": "John Baptist Mukasa",
      "primary_phone": "0772554433"
    }
  ]
}

POST ?action=missing_resolve /missing-alerts/resolve

Bearer Token

Mark a missing alert as resolved when the student is safely located.

Request Payload:

{ "record_id": 14, "note": "Learner located in library study annex." }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Missing alert marked as resolved successfully!",
  "data": { "record_id": 14, "resolved_by": "Dr. Grace Mukasa" }
}

Module 6

Boarder Gate Passes & Approvals

GET ?action=gate_passes_pending /gate-passes/pending

Bearer Token

List pending boarder gate passes requiring Matron/Warden endorsement.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Pending boarder gate passes retrieved",
  "data": [
    {
      "id": 7,
      "student_name": "Nakato Rebecca",
      "admission_no": "ADM-2026-014",
      "dorm_name": "Kabalega Block (Girls)",
      "bed_number": "Bed 12",
      "reason": "Weekend medical checkup accompanied by parent",
      "departure_time": "2026-08-31 09:00:00"
    }
  ]
}

POST ?action=gate_pass_approve /gate-passes/approve

Bearer Token

Approve or reject student exit permission slip.

Request Payload:

{ "pass_id": 7, "decision": "approved", "remarks": "Parent contacted and verified." }

Module 7

Sickbay Transfers & Health Reporting

POST ?action=health_transfer_sickbay /health/transfer-sickbay

Bearer Token

Transfer sick boarder to school infirmary / clinic with symptoms, temperature, and notes. Notifies parent immediately via SMS.

Request Payload:

{
  "student_id": 14,
  "symptoms": "High fever, chills, stomach pain",
  "temperature_celsius": 38.8,
  "notes": "Admitted to school infirmary Bed 3. Nurse on duty notified."
}

Sample Response:

{
  "success": true,
  "status_code": 201,
  "message": "Student transferred to school sickbay and parent alerted.",
  "data": { "incident_id": 12, "student_id": 14, "temperature": 38.8 }
}

Module 8

Direct Parent SMS

POST ?action=sms_send_parent /sms/send-parent

Bearer Token

Send direct urgent SMS to parent regarding student's welfare in the dormitory.

Request Payload:

{
  "phone": "+256772554433",
  "message": "Dear Parent, please remember to send warm blankets for Rebecca this weekend. - Matron Grace"
}

Module 9

Shift GPS Attendance & Clock-In

POST ?action=attendance_clock_in /attendance/clock-in

Bearer Token

Matron shift clock-in / clock-out with GPS coordinates, IP, and device info.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Matron shift check-in recorded successfully at 06:00 PM",
  "data": { "action": "clock_in", "check_in_time": "18:00:00", "date": "2026-08-30" }
}

Module 10

Salary, Allowances & Payslips

GET ?action=payroll_summary /payroll/summary

Bearer Token

Matron salary package, night shift allowance, and payment vouchers history.

Module 11

Messaging & Staff Chat

GET ?action=chats /chats

Bearer Token

List matron chat tickets with administration, school nurse, and parents.

Module 12

Circulars & Alerts

GET ?action=notifications /notifications

Bearer Token

Real-time alerts, health bulletins, and official school circulars.

Module 13

Academic Calendar & Visitation Schedule

GET ?action=calendar_events /calendar/events

Bearer Token

Term opening/closing dates, visitation days, sports days, and midterm breaks.

Module 14

Emergency & Campus Safety

POST ?action=emergency_panic /emergency/panic-report

SOS Panic Dispatch

One-tap emergency panic button triggered by matron (Fire, Intrusion, Night Medical Emergency).

Request Payload:

{
  "emergency_type": "Dormitory Fire Alarm / Power Short",
  "dormitory_location": "Kabalega Block (Girls) Wing B",
  "latitude": 0.3541,
  "longitude": 32.5912,
  "notes": "Smoke detected near power mains. All learners evacuated to assembly point."
}

Sample Response:

{
  "success": true,
  "status_code": 201,
  "message": "Emergency panic broadcast dispatched to school administration and campus security!",
  "data": { "incident_id": 14, "emergency_type": "Dormitory Fire Alarm / Power Short", "status": "Dispatched" }
}

SDK Code Examples

React Native / TypeScript Integration matronApi.ts

import axios from 'axios';

const BASE_URL = 'http://localhost/edupulse/index.php?api=matron';
export const matronApi = axios.create({ baseURL: BASE_URL });

export const setMatronAuthToken = (token: string) => {
  matronApi.defaults.headers.common['Authorization'] = `Bearer ${token}`;
};

// 1. Submit Night Inspection Roll Call
export const submitNightRollCall = async (dormId: number, statuses: Record, notes: Record) => {
  const res = await matronApi.post('&action=rollcall_submit', {
    dormitory_id: dormId,
    roll_call_date: new Date().toISOString().split('T')[0],
    status: statuses,
    student_notes: notes,
  });
  return res.data;
};

// 2. Transfer Boarder to Sickbay
export const admitToSickbay = async (studentId: number, symptoms: string, temp: number) => {
  const res = await matronApi.post('&action=health_transfer_sickbay', {
    student_id: studentId,
    symptoms,
    temperature_celsius: temp,
  });
  return res.data;
};

Flutter / Dart Integration matron_api_service.dart

import 'dart:convert';
import 'package:http/http.dart' as http;

class MatronApiService {
  static const String baseUrl = 'http://localhost/edupulse/index.php?api=matron';
  String? _authToken;

  void setToken(String token) {
    _authToken = token;
  }

  Map<String, String> get _headers => {
    'Content-Type': 'application/json',
    if (_authToken != null) 'Authorization': 'Bearer $_authToken',
  };

  // 1. Submit Dormitory Roll Call
  Future<Map<String, dynamic>> submitRollCall(int dormId, Map<String, String> statuses) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=rollcall_submit'),
      headers: _headers,
      body: jsonEncode({
        'dormitory_id': dormId,
        'status': statuses,
      }),
    );
    return jsonDecode(response.body);
  }
}