⚡ Complete REST API Specification with Full Response Payloads
Parent Portal Mobile REST API
Exhaustive reference document containing every endpoint for the EduPulse Parent Mobile App, including all request parameters, example request JSON, and complete realistic success/error responses.
Base URL
https://your-domain.com/index.php?api=parent
Payload Format
application/json (UTF-8)
Auth Header
Authorization: Bearer <TOKEN>
Authentication & Security
Protected endpoints require the Authorization: Bearer <API_TOKEN> HTTP header. Tokens are generated upon completing 4-digit PIN setup or login.
// Example API Request Header
Authorization: Bearer d3be490a79bb4eedbe880b38411653d2771b807ddf9dda75204231b16b5f86ce
Content-Type: application/json
Authorization: Bearer d3be490a79bb4eedbe880b38411653d2771b807ddf9dda75204231b16b5f86ce
Content-Type: application/json
Standard Response Envelope
Success Response (200 OK)
{
"success": true,
"status_code": 200,
"message": "Operation completed successfully",
"data": { ... },
"errors": null
}
Error Response (422 / 401)
{
"success": false,
"status_code": 422,
"message": "Please provide a valid 4-digit PIN.",
"data": null,
"errors": null
}
Module 1
Authentication & Account Lifecycle
POST
?action=auth_phone
/auth/phone
Public
Submits parent's phone number. Checks if parent has a PIN set or initiates a 4-digit SMS OTP.
Request Payload:
{ "phone": "0757755338" }Sample Response (New Parent -> OTP Sent):
{
"success": true,
"status_code": 200,
"message": "A 4-digit verification code has been sent to your phone via SMS.",
"data": {
"phone": "0757755338",
"is_pin_set": false,
"step": "verify_otp",
"sms_sent": true,
"otp_code": null
},
"errors": null
}Sample Response (Returning Parent -> Enter PIN):
{
"success": true,
"status_code": 200,
"message": "Phone verified. Please enter your 4-digit security PIN.",
"data": {
"phone": "0757755338",
"is_pin_set": true,
"step": "enter_pin",
"name": "Sarah Kimuli"
},
"errors": null
}
POST
?action=auth_verify_otp
/auth/verify-otp
Public
Verifies the 4-digit SMS OTP code.
Request Payload:
{ "phone": "0757755338", "otp_code": "7779" }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Verification successful. Please set up your 4-digit security PIN and details.",
"data": {
"phone": "0757755338",
"step": "set_pin"
},
"errors": null
}
POST
?action=auth_resend_otp
/auth/resend-otp
Public
Dispatches a fresh 4-digit SMS OTP code.
Request Payload:
{ "phone": "0757755338" }Sample Response:
{
"success": true,
"status_code": 200,
"message": "A new verification code has been dispatched to your phone.",
"data": {
"phone": "0757755338",
"sms_sent": true
},
"errors": null
}
POST
?action=auth_set_pin
/auth/set-pin
Public (Post-OTP)
Completes registration by saving a 4-digit PIN and profile details. Returns user object with Bearer token.
Request Payload:
{
"phone": "0757755338",
"pin": "1234",
"confirm_pin": "1234",
"full_name": "Sarah Kimuli",
"email": "sarah.kimuli@gmail.com",
"occupation": "Accountant",
"address": "Muyenga, Kampala"
}Sample Response:
{
"success": true,
"status_code": 200,
"message": "Parent account setup completed successfully!",
"data": {
"token": "d3be490a79bb4eedbe880b38411653d2771b807ddf9dda75204231b16b5f86ce",
"user": {
"id": 28,
"name": "Sarah Kimuli",
"email": "sarah.kimuli@gmail.com",
"phone": "0757755338",
"role_id": 6,
"role_name": "parent"
},
"parent": {
"id": 14,
"user_id": 28,
"full_name": "Sarah Kimuli",
"phone": "0757755338",
"email": "sarah.kimuli@gmail.com",
"occupation": "Accountant",
"address": "Muyenga, Kampala"
}
},
"errors": null
}
POST
?action=auth_login_pin
/auth/login-pin
Public
Fast login for returning parents using registered phone number and 4-digit PIN.
Request Payload:
{ "phone": "0757755338", "pin": "1234" }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Login successful. Welcome back!",
"data": {
"token": "d3be490a79bb4eedbe880b38411653d2771b807ddf9dda75204231b16b5f86ce",
"user": {
"id": 28,
"name": "Sarah Kimuli",
"phone": "0757755338",
"role_name": "parent"
},
"parent": {
"id": 14,
"full_name": "Sarah Kimuli",
"phone": "0757755338",
"occupation": "Accountant",
"address": "Muyenga, Kampala"
}
},
"errors": null
}
POST
?action=auth_forgot_pin
/auth/forgot-pin
Public
Requests a 4-digit PIN reset code via SMS.
Request Payload:
{ "phone": "0757755338" }Sample Response:
{
"success": true,
"status_code": 200,
"message": "A 4-digit PIN reset code has been sent to your phone via SMS.",
"data": {
"phone": "0757755338",
"sms_sent": true
},
"errors": null
}
POST
?action=auth_reset_pin
/auth/reset-pin
Public
Saves new PIN with verified OTP code.
Request Payload:
{ "phone": "0757755338", "otp_code": "5421", "new_pin": "9876", "confirm_pin": "9876" }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Your security PIN has been reset successfully!",
"data": {
"token": "a823b1239c44dd9211029384756abcdef1234567890abcdef1234567890abc",
"user": {
"id": 28,
"name": "Sarah Kimuli",
"phone": "0757755338"
}
},
"errors": null
}
POST
?action=auth_logout
/auth/logout
Bearer Token
Revokes the active Bearer token and logs out.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "You have been logged out successfully.",
"data": null,
"errors": null
}
GET
?action=profile
/profile
Bearer Token
Retrieves logged-in parent details (name, email, phone, occupation, address, national ID, avatar).
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Parent profile retrieved",
"data": {
"user": {
"id": 28,
"name": "Sarah Kimuli",
"email": "sarah.kimuli@gmail.com",
"phone": "0757755338",
"photo_url": "uploads/parents/parent_1784619000_123.jpg",
"role_name": "parent"
},
"parent": {
"id": 14,
"user_id": 28,
"full_name": "Sarah Kimuli",
"phone": "0757755338",
"email": "sarah.kimuli@gmail.com",
"occupation": "Accountant",
"address": "Muyenga, Kampala",
"national_id": "CM9012345678AB"
}
},
"errors": null
}
POST
?action=profile_update
/profile/update
Bearer Token
Updates parent profile & avatar image (Multipart form data: avatar_file).
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Profile updated successfully!",
"data": {
"user": {
"id": 28,
"name": "Sarah Kimuli Namakula",
"photo_url": "uploads/parents/parent_1784620000_456.jpg"
}
},
"errors": null
}
Module 2
Children & Student Management
GET
?action=children
/children
Bearer Token
Lists all linked children with school name, logo, class, stream, photo, and active subscription status.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Children retrieved",
"data": [
{
"id": 8,
"student_code": "STU-2026-008",
"admission_no": "ADM-008",
"first_name": "Mukibi",
"last_name": "Henry",
"gender": "Male",
"dob": "2015-05-12",
"photo_url": "uploads/students/stu_1784617116_101.jpg",
"class_id": 1,
"class_name": "Primary 1",
"stream_id": 2,
"stream_name": "Blue",
"school_id": 1,
"school_name": "Zana Mixed Secondary School",
"school_logo": "uploads/logos/school_logo_1.png",
"billing_type": "paid",
"parent_term_fee_usd": "1.00",
"parent_term_fee_ugx": "3700.00",
"has_active_subscription": true
}
],
"errors": null
}
GET
?action=child_dashboard&student_id={id}
/children/dashboard
Bearer Token
Single unified live dashboard: today rollcall, active live lesson, next lesson, fee balance, active medical alerts, boarding roll call, and bus status.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Dashboard data retrieved",
"data": {
"student": {
"id": 8,
"first_name": "Mukibi",
"last_name": "Henry",
"student_code": "STU-2026-008",
"class_name": "Primary 1",
"stream_name": "Blue",
"school_name": "Zana Mixed Secondary School"
},
"subscription": {
"has_active_subscription": true,
"term_name": "Term 2 2026",
"term_fee_ugx": 3700.00
},
"today_rollcall": {
"status": "present",
"arrival_time": "07:45:00",
"teacher_name": "Mr. Okello John",
"teacher_phone": "+256 701 444 555"
},
"active_lesson": {
"subject_name": "Mathematics",
"room_no": "Room 4A",
"teacher_name": "Mr. Ssemakula Ben",
"start_time": "10:30:00",
"end_time": "11:50:00",
"lesson_state": "in_progress"
},
"fees_summary": {
"total_required_ugx": 850000.00,
"discount_ugx": 50000.00,
"total_paid_ugx": 600000.00,
"balance_ugx": 200000.00
},
"health_alerts": [],
"dorm_rollcall": {
"status": "present",
"dorm_name": "Lumumba House"
},
"bus_transport": {
"status": "dropped_home",
"vehicle_number": "UBJ 452K",
"driver_name": "Mugisha David"
}
},
"errors": null
}
GET
?action=schools&search={query}&district={district}
/schools
Bearer Token
Searches and lists registered schools for child claiming.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Schools retrieved",
"data": [
{
"id": 1,
"name": "Zana Mixed Secondary School",
"school_code": "SCH-ZANA-01",
"logo_url": "uploads/logos/school_logo_1.png",
"district": "Wakiso",
"address": "Entebbe Road, Zana",
"phone": "+256 700 111 222",
"level_category": "Secondary",
"ownership_type": "Private"
}
],
"errors": null
}
GET
?action=school_classes&school_id={id}
/schools/classes
Bearer Token
Returns all classes for a selected school.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Classes retrieved",
"data": [
{ "id": 1, "class_name": "Primary 1", "level_type": "Primary", "numeric_order": 1 },
{ "id": 2, "class_name": "Primary 2", "level_type": "Primary", "numeric_order": 2 }
],
"errors": null
}
GET
?action=class_students&class_id={id}
/classes/students
Bearer Token
Returns student roster in a class with claim limits and whether claimed.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Class students retrieved",
"data": {
"max_parents_allowed": 2,
"students": [
{
"id": 8,
"first_name": "Mukibi",
"last_name": "Henry",
"student_code": "STU-2026-008",
"admission_no": "ADM-008",
"gender": "Male",
"photo_url": "uploads/students/stu_8.jpg",
"class_name": "Primary 1",
"stream_name": "Blue",
"linked_parents_count": 1,
"linked_by_me": 1,
"max_parents_allowed": 2,
"is_fully_claimed": false
}
]
},
"errors": null
}
POST
?action=students_link
/students/link
Bearer Token
Self-links one or more students to the parent account.
Request Payload:
{ "student_ids": [8, 10] }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Student linking processed successfully",
"data": {
"linked_students": ["Mukibi Henry", "Mukibi Ham"],
"blocked_students": []
},
"errors": null
}
GET
?action=student_id_card&student_id={id}
/students/id-card
Bearer Token
Returns digital student & parent ID card data (barcode data, QR code string, school stamp, signature).
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Digital ID card payload retrieved",
"data": {
"student": {
"id": 8,
"first_name": "Mukibi",
"last_name": "Henry",
"student_code": "STU-2026-008",
"class_name": "Primary 1",
"school_name": "Zana Mixed Secondary School",
"school_logo": "uploads/logos/school_logo_1.png",
"stamp_url": "uploads/stamps/stamp_1.jpg",
"signature_url": "uploads/signatures/sig_1.jpeg"
},
"parent": {
"full_name": "Sarah Kimuli",
"phone": "0757755338"
},
"barcode_data": "STU-2026-008",
"qr_string": "EDUPULSE-ID:8:STU-2026-008:SCH-ZANA-01"
},
"errors": null
}
Module 3
Daily Roll & Live Lesson Accountability
GET
?action=attendance_today&student_id={id}
/attendance/today
Bearer Token
Today morning roll call status (present, absent, late), arrival time, teacher photo & phone.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Today attendance retrieved",
"data": {
"status": "present",
"arrival_time": "07:45:00",
"date": "2026-08-30",
"notes": null,
"teacher_name": "Mr. Okello John",
"teacher_photo": "uploads/teachers/tch_1.jpg",
"teacher_phone": "+256 701 444 555"
},
"errors": null
}
GET
?action=attendance_history&student_id={id}&limit=30
/attendance/history
Bearer Token
Attendance summary (total days, present, absent, late, percentage rate) + date-by-date history log.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Attendance history retrieved",
"data": {
"summary": {
"total_days_recorded": 58,
"present": 56,
"absent": 1,
"late": 1,
"attendance_rate_pct": 96.6
},
"records": [
{
"id": 142,
"date": "2026-08-29",
"status": "present",
"arrival_time": "07:40:00",
"notes": null,
"teacher_name": "Mr. Okello John"
}
]
},
"errors": null
}
GET
?action=lessons_today&student_id={id}
/lessons/today
Bearer Token
Today timetable with live lesson status and student attendance per lesson.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Today timetable and lesson accountability retrieved",
"data": [
{
"id": 14,
"room_no": "Room 4A",
"day_of_week": "Monday",
"start_time": "10:30:00",
"end_time": "11:50:00",
"lesson_state": "in_progress",
"subject_name": "Mathematics",
"subject_code": "MTC",
"teacher_name": "Mr. Ssemakula Ben",
"teacher_phone": "+256 702 333 444",
"student_lesson_status": "present",
"marked_at": "2026-08-30 10:35:12"
}
],
"errors": null
}
Module 4
Fees & IoTec Mobile Money Gateway
GET
?action=fees_summary&student_id={id}
/fees/summary
Bearer Token
Total fees required, bursary/discounts, net required, amount paid, and outstanding balance.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Fee summary retrieved",
"data": {
"total_structure_fees_ugx": 850000.00,
"discount_ugx": 50000.00,
"discount_reason": "Bursary Discount",
"net_required_ugx": 800000.00,
"total_paid_ugx": 600000.00,
"outstanding_balance_ugx": 200000.00
},
"errors": null
}
GET
?action=fee_structure&student_id={id}
/fees/structure
Bearer Token
Itemized fee breakdown with per-item paid/balance status.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Fee structure retrieved",
"data": [
{
"id": 1,
"fee_type": "Tuition Fee",
"amount_ugx": "500000.00",
"item_paid_ugx": 500000.00,
"item_balance_ugx": 0.00,
"item_status": "paid"
},
{
"id": 2,
"fee_type": "Development Fee",
"amount_ugx": "200000.00",
"item_paid_ugx": 100000.00,
"item_balance_ugx": 100000.00,
"item_status": "partial"
},
{
"id": 3,
"fee_type": "School Meals",
"amount_ugx": "150000.00",
"item_paid_ugx": 0.00,
"item_balance_ugx": 150000.00,
"item_status": "unpaid"
}
],
"errors": null
}
GET
?action=fee_history&student_id={id}
/fees/history
Bearer Token
List of all historical payments, receipt numbers, and verification statuses.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Payment history retrieved",
"data": [
{
"id": 102,
"receipt_no": "REC-20260830-101",
"amount_paid_ugx": "250000.00",
"payment_method": "mobile_money",
"payment_reference": "IOTEC-MM-109283",
"payment_date": "2026-08-30 08:30:00",
"verification_status": "verified",
"notes": "Payment for: Tuition Fee via Mobile Money"
}
],
"errors": null
}
GET
?action=receipt_details&receipt_no={no}
/fees/receipt
Bearer Token
Full digital receipt breakdown with school stamp, bursar signature, and fee line items.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Receipt details retrieved",
"data": {
"id": 102,
"receipt_no": "REC-20260830-101",
"amount_paid_ugx": "250000.00",
"first_name": "Mukibi",
"last_name": "Henry",
"class_name": "Primary 1",
"school_name": "Zana Mixed Secondary School",
"school_logo": "uploads/logos/school_logo_1.png",
"stamp_url": "uploads/stamps/stamp_1.jpg",
"bursar_signature_url": "uploads/signatures/bursar_sig.png"
},
"errors": null
}
POST
?action=pay_fees_momo
/fees/pay-mobile-money
Bearer Token
Initiates School Fee payment via IoTec Mobile Money prompt.
Request Payload:
{
"student_id": 8,
"amount_ugx": 250000,
"phone": "256752999888",
"fee_type": "Tuition Fee"
}Sample Response:
{
"success": true,
"status_code": 200,
"message": "Mobile Money PIN prompt sent to 256752999888. Please enter your PIN on your phone to complete payment.",
"data": {
"transaction_id": "IOTEC-MM-20260830-109283",
"reference": "FEE-MM-20260830-4921",
"amount_ugx": 250000,
"phone": "256752999888"
},
"errors": null
}
POST
?action=pay_subscription_momo
/subscription/pay
Bearer Token
Pays Term Accountability Portal subscription ($1 / 3,700 UGX) via Mobile Money.
Request Payload:
{ "student_id": 8, "phone_number": "256752999888" }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Mobile Money PIN prompt sent to 256752999888. Complete on your device to unlock Term Accountability.",
"data": {
"transaction_id": "SUB-MM-2026-9182",
"amount_ugx": 3700.00
},
"errors": null
}
GET
?action=payment_status&transaction_id={id}
/payments/status
Bearer Token
Polls transaction status (SUCCESSFUL, PENDING, FAILED).
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Payment status checked",
"data": {
"success": true,
"status": "SUCCESSFUL",
"transaction_id": "IOTEC-MM-20260830-109283",
"message": "Transaction completed successfully."
},
"errors": null
}
Module 5
Academics & UNEB Report Cards
GET
?action=report_card_terms&student_id={id}
/report-cards/terms
Bearer Token
Lists available academic terms and years.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Terms and academic years retrieved",
"data": {
"terms": [
{ "id": 2, "term_name": "Term 2 2026", "start_date": "2026-05-25", "end_date": "2026-08-28", "is_current": 1 }
],
"academic_years": [
{ "id": 1, "year_label": "2026", "is_current": 1 }
]
},
"errors": null
}
GET
?action=report_card_view&student_id={id}&term_id={term_id}
/report-cards/view
Bearer Token
Returns full UNEB report card data: subject marks, UNEB grades (D1-F9), class position, teacher remarks, headteacher remarks, and digital school stamp.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Report card data retrieved",
"data": {
"student": {
"first_name": "Mukibi",
"last_name": "Henry",
"class_name": "Primary 1",
"school_name": "Zana Mixed Secondary School",
"stamp_url": "uploads/stamps/stamp_1.jpg",
"signature_url": "uploads/signatures/sig_1.jpeg"
},
"report_card": {
"overall_percentage": "88.50",
"overall_grade": "D1",
"teacher_remarks": "Outstanding grasp of concepts and active participation.",
"headteacher_remarks": "Promoted with distinction.",
"attendance_days_present": 62,
"attendance_days_absent": 1
},
"results": [
{
"subject_name": "Mathematics",
"mark_score": "92.00",
"max_score": "100.00",
"grade": "D1",
"teacher_comment": "Excellent numerical skills."
},
{
"subject_name": "English Language",
"mark_score": "85.00",
"max_score": "100.00",
"grade": "D2",
"teacher_comment": "Very good grammar."
}
]
},
"errors": null
}
Module 6
Health & Infirmary / Clinic Monitoring
GET
?action=health_incidents&student_id={id}
/health/incidents
Bearer Token
Lists active and historical clinic visits (symptoms, temperature, BP, diagnosis, nurse notes, discharge status).
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Health records retrieved",
"data": [
{
"id": 5,
"incident_type": "Mild Fever & Headache",
"symptoms": "High temperature, body weakness",
"diagnosis": "Early Stage Malaria",
"temperature_celsius": "38.6",
"blood_pressure": "110/75",
"nurse_notes": "Administered Coartem & Paracetamol. Resting in school clinic.",
"status": "Admitted in Clinic",
"parent_authorized_at": null,
"created_at": "2026-08-30 09:15:00"
}
],
"errors": null
}
GET
?action=health_incident_logs&incident_id={id}
/health/incident-logs
Bearer Token
Medical timeline audit trail for treatment changes and nurse notes.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Health incident timeline retrieved",
"data": [
{
"id": 12,
"incident_id": 5,
"action_type": "Vital Signs Checked",
"action_details": "Temperature measured at 38.6C, BP 110/75. Oral medication given.",
"performed_by_id": 9,
"created_at": "2026-08-30 09:20:00"
}
],
"errors": null
}
POST
?action=health_authorize
/health/authorize
Bearer Token
Parent medical consent for hospital referral or specialized medication.
Request Payload:
{
"incident_id": 5,
"authorization_type": "hospital_referral",
"notes": "Approved for transfer to Nsambya Hospital"
}Sample Response:
{
"success": true,
"status_code": 200,
"message": "Medical procedure / hospital referral authorization recorded successfully.",
"data": null,
"errors": null
}
POST
?action=health_dismiss_alert
/health/dismiss
Bearer Token
Dismisses active health alert banner from mobile dashboard.
Request Payload:
{ "incident_id": 5 }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Health alert dismissed from dashboard.",
"data": null,
"errors": null
}
Module 7
Boarding & Dormitory Accountability
GET
?action=boarding_rollcalls&student_id={id}
/boarding/roll-calls
Bearer Token
Night dormitory roll call history: present, absent, sick_in_clinic with roll call timestamp, dormitory name, and matron/patron name.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Boarding roll call history retrieved",
"data": [
{
"id": 89,
"status": "present",
"notes": null,
"is_resolved": 1,
"roll_call_date": "2026-08-29",
"roll_call_time": "21:30:00",
"dorm_name": "Lumumba House",
"dorm_gender": "Boys",
"taken_by_name": "Patron David"
}
],
"errors": null
}
Module 8
Bus & Transport Tracking
GET
?action=transport_latest&student_id={id}
/transport/latest
Bearer Token
Latest bus trip status: morning_pickup / evening_dropoff, route, vehicle plate number, driver name, driver phone, and pickup/dropoff timestamp.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Latest transport status retrieved",
"data": {
"trip_type": "evening_dropoff",
"vehicle_number": "UBJ 452K",
"route_name": "Muyenga - Bunga Route",
"driver_name": "Mugisha David",
"driver_phone": "+256 772 112 233",
"driver_code": "DRV-004",
"status": "dropped_home",
"start_time": "16:30:00",
"created_at": "2026-08-29 17:45:00"
},
"errors": null
}
Module 9
Gate Passes & Exit Permissions
GET
?action=gate_passes&student_id={id}
/gate-passes
Bearer Token
Lists issued gate passes / permission slips with status (active, completed, overdue).
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Gate passes retrieved",
"data": [
{
"id": 15,
"pass_number": "GP-20260830-742",
"reason": "Hospital Dental Appointment",
"departure_time": "2026-08-31 09:00:00",
"expected_return_time": "2026-08-31 15:00:00",
"status": "pending",
"first_name": "Mukibi",
"last_name": "Henry",
"class_name": "Primary 1"
}
],
"errors": null
}
POST
?action=gate_pass_request
/gate-passes/request
Bearer Token
Submits exit permission slip request from parent to school administration.
Request Payload:
{
"student_id": 8,
"reason": "Hospital Dental Appointment",
"departure_time": "2026-08-31 09:00:00",
"expected_return_time": "2026-08-31 15:00:00"
}Sample Response:
{
"success": true,
"status_code": 200,
"message": "Gate pass request submitted successfully for school administration approval.",
"data": {
"pass_number": "GP-20260830-742"
},
"errors": null
}
Module 10
Requirements & Uniforms / Stationeries
GET
?action=requirements&student_id={id}
/requirements
Bearer Token
Lists mandatory and optional school items with student fulfillment status (fulfilled, partial, pending) and quantities.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Requirements retrieved",
"data": [
{
"id": 1,
"item_name": "Oxford Mathematical Set",
"quantity_description": "1 Piece",
"is_mandatory": 1,
"student_status": "fulfilled",
"quantity_provided": "1"
},
{
"id": 2,
"item_name": "Rotatrim Photocopy Paper (Ream)",
"quantity_description": "2 Reams (500 Sheets)",
"is_mandatory": 1,
"student_status": "pending",
"quantity_provided": "0"
}
],
"errors": null
}
Module 11
Teachers Directory
GET
?action=teachers&student_id={id}
/teachers
Bearer Token
Directory of subject instructors teaching the child's class with photos, subject names, phone numbers, and qualifications.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Teachers directory retrieved",
"data": [
{
"id": 2,
"teacher_name": "Mr. Ssemakula Ben",
"email": "ben.ssemakula@school.ug",
"phone": "+256 702 333 444",
"subject_name": "Mathematics",
"qualification": "B.Ed Mathematics (Mak)",
"photo_url": "uploads/teachers/tch_2.jpg",
"class_name": "Primary 1"
}
],
"errors": null
}
Module 12
Support Chat & In-App Messaging
GET
?action=chats
/chats
Bearer Token
Lists all open and closed support tickets/chats for the parent.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Chats retrieved",
"data": [
{
"id": 9,
"ticket_number": "CHAT-20260830-8192",
"subject": "Inquiry regarding swimming gala fees",
"category": "school_admin",
"status": "open",
"priority": "medium",
"last_message_at": "2026-08-30 11:20:00",
"school_name": "Zana Mixed Secondary School",
"student_first": "Mukibi",
"student_last": "Henry"
}
],
"errors": null
}
POST
?action=chat_create
/chats/create
Bearer Token
Opens a new conversation with school staff. Multipart params: subject, message, category, student_id, attachment.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Support ticket created successfully",
"data": {
"chat_id": 9,
"ticket_number": "CHAT-20260830-8192"
},
"errors": null
}
GET
?action=chat_messages&chat_id={id}
/chats/messages
Bearer Token
Fetches message thread in a chat and automatically marks incoming messages as read.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Chat messages retrieved",
"data": {
"chat": {
"id": 9,
"ticket_number": "CHAT-20260830-8192",
"subject": "Inquiry regarding swimming gala fees"
},
"messages": [
{
"id": 21,
"chat_id": 9,
"sender_id": 28,
"sender_role": "parent",
"sender_name": "Sarah Kimuli",
"message": "Good morning, please clarify the uniform pickup dates.",
"attachment_url": null,
"is_read": 1,
"created_at": "2026-08-30 08:15:00"
},
{
"id": 22,
"chat_id": 9,
"sender_id": 4,
"sender_role": "school_admin",
"sender_name": "Headteacher Office",
"message": "Good morning Mrs. Kimuli. Uniforms will be distributed on Tuesday at the bursar's office.",
"attachment_url": null,
"is_read": 1,
"created_at": "2026-08-30 08:45:00"
}
]
},
"errors": null
}
POST
?action=chat_send
/chats/send
Bearer Token
Sends a reply message with optional photo/document attachment.
Request Payload:
{ "chat_id": 9, "message": "Thank you for the prompt update!" }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Message sent successfully",
"data": {
"message_id": 23,
"attachment_url": null
},
"errors": null
}
Module 13
Announcements & Notifications
GET
?action=announcements&school_id={id}&limit=20
/announcements
Bearer Token
Official school circulars and announcements targeted to parents.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Announcements retrieved",
"data": [
{
"id": 8,
"title": "End of Term 2 Academic Schedule & Visitation Day",
"content": "Dear Parents and Guardians, please note that our annual Visitation Day will be held on Friday, August 28th...",
"target_audience": "parents",
"created_at": "2026-08-25 14:00:00",
"author_name": "School Administration"
}
],
"errors": null
}
GET
?action=notifications&unread_only=false
/notifications
Bearer Token
Real-time notification feed (arrival clock-in, missed lesson, medical incident, bus dropoff) with unread count.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Notifications retrieved",
"data": {
"unread_count": 2,
"notifications": [
{
"id": 41,
"title": "Arrival Clock-In Marked",
"message": "Mukibi Henry arrived at school at 07:45 AM and was marked present.",
"type": "attendance",
"is_read": 0,
"created_at": "2026-08-30 07:46:12"
},
{
"id": 40,
"title": "New School Announcement",
"message": "New circular published regarding Term 2 exams.",
"type": "announcement",
"is_read": 0,
"created_at": "2026-08-29 16:00:00"
}
]
},
"errors": null
}
POST
?action=notification_read
/notifications/read
Bearer Token
Marks a specific notification as read.
Request Payload:
{ "id": 41 }Sample Response:
{
"success": true,
"status_code": 200,
"message": "Notification marked as read",
"data": null,
"errors": null
}
POST
?action=notifications_read_all
/notifications/read-all
Bearer Token
Marks all notifications for the user as read.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "All notifications marked as read",
"data": null,
"errors": null
}
Module 14
Academic Calendar & School Events
GET
?action=calendar_events&school_id={id}&start_date={d}&end_date={d}
/calendar/events
Bearer Token
Term dates, exam schedules, visitation days, sports days, and public holidays.
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Calendar events retrieved",
"data": [
{
"id": 3,
"event_title": "Mid-Term Examination Week",
"event_type": "exam",
"start_date": "2026-08-15",
"end_date": "2026-08-19",
"color_hex": "#dc2626"
},
{
"id": 4,
"event_title": "Term 2 Visitation & Sports Day",
"event_type": "event",
"start_date": "2026-08-28",
"end_date": "2026-08-28",
"color_hex": "#16a34a"
}
],
"errors": null
}
Module 15
Emergency Response & Safety Hotlines
GET
?action=emergency_alerts&school_id={id}
/emergency/alerts
Bearer Token
Active emergency alerts (lockdown, weather, fire) + emergency directory (Police, Ambulance, Fire Brigade, School Command).
Sample Response:
{
"success": true,
"status_code": 200,
"message": "Emergency alerts retrieved",
"data": {
"active_incidents": [],
"agency_contacts": [
{
"id": 1,
"agency_type": "Police Emergency",
"agency_name": "Kabalagala Police Division",
"phone_primary": "999",
"phone_secondary": "+256 414 123 456"
},
{
"id": 2,
"agency_type": "Medical / Ambulance",
"agency_name": "Nsambya Emergency Medical Rescue",
"phone_primary": "911",
"phone_secondary": "+256 772 000 111"
},
{
"id": 3,
"agency_type": "Fire Brigade",
"agency_name": "Kampala Central Fire Station",
"phone_primary": "112",
"phone_secondary": "+256 414 999 112"
}
]
},
"errors": null
}Client SDK Code Examples
React Native / TypeScript Integration
parentApi.ts
import axios from 'axios';
const BASE_URL = 'https://your-domain.com/index.php?api=parent';
export const parentApi = axios.create({ baseURL: BASE_URL });
export const setAuthToken = (token: string) => {
parentApi.defaults.headers.common['Authorization'] = `Bearer ${token}`;
};
// 1. PIN Login
export const loginWithPin = async (phone: string, pin: string) => {
const res = await parentApi.post('&action=auth_login_pin', { phone, pin });
if (res.data.success) {
setAuthToken(res.data.data.token);
}
return res.data;
};
// 2. Fetch Live Dashboard
export const getChildDashboard = async (studentId?: number) => {
const query = studentId ? `&action=child_dashboard&student_id=${studentId}` : '&action=child_dashboard';
const res = await parentApi.get(query);
return res.data.data;
};
// 3. Pay Fees via Mobile Money
export const payFeesMobileMoney = async (studentId: number, amountUgx: number, phone: string, feeType: string) => {
const res = await parentApi.post('&action=pay_fees_momo', {
student_id: studentId,
amount_ugx: amountUgx,
phone,
fee_type: feeType,
});
return res.data;
};
Flutter / Dart Integration
parent_api_service.dart
import 'dart:convert';
import 'package:http/http.dart' as http;
class ParentApiService {
static const String baseUrl = 'https://your-domain.com/index.php?api=parent';
String? _authToken;
void setToken(String token) => _authToken = token;
Map get _headers => {
'Content-Type': 'application/json',
if (_authToken != null) 'Authorization': 'Bearer $_authToken',
};
Future> loginWithPin(String phone, String pin) async {
final res = await http.post(
Uri.parse('$baseUrl&action=auth_login_pin'),
headers: _headers,
body: jsonEncode({'phone': phone, 'pin': pin}),
);
final data = jsonDecode(res.body);
if (data['success'] == true) {
setToken(data['data']['token']);
}
return data;
}
Future> getChildDashboard([int? studentId]) async {
final query = studentId != null ? '&action=child_dashboard&student_id=$studentId' : '&action=child_dashboard';
final res = await http.get(Uri.parse('$baseUrl$query'), headers: _headers);
return jsonDecode(res.body)['data'];
}
}