EduPulse Smart Schools
EduPulse Africa API Specification

Developer REST API Explorer & Interactive Reference

arrow_back API Hub Directory home Portal
⚡ Complete Teacher REST API Specification

Teacher Mobile App REST API

Production API reference for the EduPulse Teacher Mobile App. Empowers teachers with GPS gate clock-in, morning student roll calls (with instant SMS alerts), live in-progress lesson management, bulk formative & summative mark entry with UNEB grading, gate pass approvals, and payslips.

Base URL http://localhost/edupulse/index.php?api=teacher
Payload Format application/json (UTF-8)
Auth Header Authorization: Bearer <TOKEN>

Authentication & Security

Teacher protected endpoints require the Authorization: Bearer <API_TOKEN> HTTP header. Tokens are generated upon logging in with email/phone and password or security PIN.

// Example Teacher API Request Header
Authorization: Bearer 878655cada76ef6e301f0d4031c9a6882c34fea36dfacef6ed54d9906c1e92ce
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": "Class ID and attendance mapping are required.",
  "data": null,
  "errors": null
}
Module 1

Authentication & Teacher Profile

POST ?action=auth_login /auth/login
Public

Authenticates teacher using email/phone and password or 4-digit PIN. Returns Bearer token, staff record, and assigned classes.

Request Payload:

{
  "login": "teacher@school.ug",
  "password": "1234"
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Teacher login successful. Welcome back!",
  "data": {
    "token": "878655cada76ef6e301f0d4031c9a6882c34fea36dfacef6ed54d9906c1e92ce",
    "user": {
      "id": 15,
      "name": "Mrs. Florence Nsubuga",
      "email": "teacher@school.ug",
      "phone": "+256 702 333 444",
      "role_id": 3,
      "role_name": "head_teacher",
      "school_id": 1,
      "school_name": "St. Julian High School"
    },
    "teacher": {
      "id": 10,
      "staff_id": "STF-2026-010",
      "qualification": "B.Ed Science",
      "specialization": "Chemistry & Biology"
    },
    "assigned_classes": [
      { "class_id": 1, "class_name": "Senior 1", "subject_name": "Chemistry" }
    ]
  }
}
POST ?action=auth_forgot_password /auth/forgot-password
Public

Dispatches a 4-digit verification code to the teacher's registered phone number via SMS.

Request Payload:

{ "login": "+256702333444" }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Password reset verification code dispatched.",
  "data": { "login": "+256702333444", "sms_sent": true, "step": "verify_reset_code" }
}
POST ?action=auth_reset_password /auth/reset-password
Public

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

Request Payload:

{ "login": "+256702333444", "otp_code": "4891", "new_password": "NewPIN1234" }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Password reset successfully! You are now logged in.",
  "data": {
    "token": "9812abcf1234567890abcdef1234567890abcdef1234567890abcdef12345678",
    "user": { "id": 15, "name": "Mrs. Florence Nsubuga", "phone": "+256 702 333 444" }
  }
}
POST ?action=auth_logout /auth/logout
Bearer Token

Revokes current user API token and ends session.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Logged out successfully.",
  "data": null
}
GET ?action=profile /profile
Bearer Token

Retrieves full teacher profile, qualifications, school data, and salary package.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Teacher profile retrieved",
  "data": {
    "user": {
      "id": 15,
      "name": "Mrs. Florence Nsubuga",
      "email": "headteacher@stjulian.edu.ug",
      "phone": "+256 702 333 444",
      "photo_url": "uploads/teachers/tch_10.jpg"
    },
    "teacher": {
      "staff_id": "STF-2026-010",
      "qualification": "B.Ed Science",
      "specialization": "Chemistry & Biology"
    },
    "salary_package": {
      "basic_salary_ugx": "850000.00",
      "allowance_ugx": "150000.00",
      "net_salary_ugx": "1000000.00"
    }
  }
}
POST ?action=profile_update /profile/update
Bearer Token

Update teacher profile details and upload new avatar photo (Multipart form data).

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Profile updated successfully!",
  "data": {
    "user": {
      "id": 15,
      "name": "Mrs. Florence Nsubuga",
      "photo_url": "uploads/teachers/tch_1784620000_123.jpg"
    }
  }
}
GET ?action=staff_id_card /staff-id-card
Bearer Token

Digital Staff ID card payload with barcode string, QR code payload, and school seal.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Teacher digital ID card payload retrieved",
  "data": {
    "teacher": {
      "id": 10,
      "staff_id": "STF-2026-010",
      "name": "Mrs. Florence Nsubuga",
      "qualification": "B.Ed Science",
      "photo_url": "uploads/teachers/tch_10.jpg"
    },
    "school": {
      "name": "St. Julian High School",
      "logo_url": "uploads/logos/school_logo_1.png",
      "stamp_url": "uploads/stamps/stamp_1.jpg",
      "signature_url": "uploads/signatures/sig_1.jpeg"
    },
    "barcode_data": "STF-2026-010",
    "qr_string": "EDUPULSE-STAFF:10:STF-2026-010:SCH-1"
  }
}
Module 2

Teacher Dashboard & Overview

GET ?action=dashboard /dashboard
Bearer Token

Unified overview with today clock-in status, punctuality metrics, today's lessons timetable, assigned classes, and pending gate pass count.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Teacher dashboard retrieved",
  "data": {
    "attendance_status": {
      "is_clocked_in": true,
      "is_clocked_out": false,
      "check_in_time": "07:45:00",
      "status": "present",
      "punctuality_pct": 98
    },
    "today_lessons": [
      {
        "id": 14,
        "start_time": "10:30:00",
        "end_time": "11:50:00",
        "room_no": "Room 4A",
        "subject_name": "Chemistry",
        "class_name": "Senior 1",
        "status": "in_progress"
      }
    ],
    "assigned_classes": [
      { "id": 1, "class_name": "Senior 1", "student_count": 38 }
    ],
    "pending_gate_passes": 2,
    "unread_notifications": 3,
    "open_chats": 1
  }
}
Module 3

Teacher Daily Attendance & GPS Clock-In

POST ?action=attendance_clock_in /attendance/clock-in
Bearer Token

Clock in / Clock out with GPS coordinates, IP address, and cutoff enforcement.

Request Payload:

{ "latitude": 0.3476, "longitude": 32.5825 }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Clock-in recorded successfully at 07:45 AM",
  "data": {
    "action": "clock_in",
    "check_in_time": "07:45:00",
    "status": "present",
    "date": "2026-08-30",
    "notes": "On Time - Gate Check-in at 07:45 AM (Cutoff: 08:15 AM)"
  }
}
GET ?action=attendance_history&limit=30 /attendance/history
Bearer Token

Past 30-100 days clock-in/out records with punctuality breakdown (present, late, excused, absent, punctuality percentage).

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Attendance history retrieved",
  "data": {
    "stats": {
      "total_days_recorded": 42,
      "present_days": 41,
      "late_days": 1,
      "punctuality_pct": 98
    },
    "records": [
      {
        "id": 104,
        "date": "2026-08-30",
        "check_in_time": "07:45:00",
        "check_out_time": "16:45:00",
        "status": "present"
      }
    ]
  }
}
Module 4

Student Daily Morning Roll Call

GET ?action=rollcall_roster&class_id=1 /students/rollcall/roster
Bearer Token

Fetch student roll call roster with today's status, arrival time, and guardian contact details.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Student roll call roster retrieved",
  "data": {
    "class": { "id": 1, "class_name": "Senior 1" },
    "students": [
      {
        "id": 8,
        "admission_no": "ADM-008",
        "first_name": "Mukibi",
        "last_name": "Henry",
        "today_status": "present",
        "parent_name": "Sarah Kimuli",
        "parent_phone": "0757755338"
      }
    ]
  }
}
POST ?action=rollcall_submit /students/rollcall/submit
Bearer Token

Bulk submit student daily attendance. Automatically sends SMS and app notification alerts to all linked parents.

Request Payload:

{
  "class_id": 1,
  "stream_id": 2,
  "attendance": {
    "8": "present",
    "10": "late",
    "12": "absent"
  },
  "notes": {
    "10": "Arrived 15 minutes late due to rain",
    "12": "Sick at home"
  }
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Daily attendance submitted successfully for 3 students!",
  "data": {
    "date": "2026-08-30",
    "class_id": 1,
    "marked_count": 3
  }
}
Module 5

Live Lessons & Timetable Accountability

GET ?action=lessons_today /lessons/today
Bearer Token

List today's scheduled lessons with live status (scheduled, in_progress, completed).

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Today lessons timetable retrieved",
  "data": [
    {
      "id": 14,
      "start_time": "10:30:00",
      "end_time": "11:50:00",
      "room_no": "Room 4A",
      "subject_name": "Chemistry",
      "class_name": "Senior 1",
      "status": "scheduled"
    }
  ]
}
GET ?action=lessons_weekly /lessons/weekly-timetable
Bearer Token

Full Monday-Sunday weekly teaching schedule grouped by day of week.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Weekly timetable retrieved",
  "data": {
    "Monday": [ { "id": 14, "start_time": "10:30:00", "subject_name": "Chemistry" } ],
    "Tuesday": [],
    "Wednesday": []
  }
}
POST ?action=lesson_toggle /lessons/toggle-status
Bearer Token

Start or End a live lesson. Automatically marks present learners and broadcasts live start/end SMS to parents.

Request Payload:

{ "lesson_id": 14, "action": "start" }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Live lesson started successfully!",
  "data": {
    "lesson_id": 14,
    "status": "in_progress",
    "actual_start": "2026-08-30 10:30:15"
  }
}
Module 6

Academic Marks Entry & UNEB Grading

GET ?action=assessment_config /academics/assessment-config
Bearer Token

Fetch terms, classes, allocated subjects, assessment periods, and max score configs.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Academic assessment configuration retrieved",
  "data": {
    "terms": [ { "id": 2, "term_name": "Term 2 2026" } ],
    "classes": [ { "id": 1, "class_name": "Senior 1" } ],
    "subjects": [ { "id": 1, "subject_name": "Chemistry" } ]
  }
}
GET ?action=marks_roster&term_id=2&class_id=1&subject_id=1 /academics/marks/roster
Bearer Token

Fetch class student list with existing marks, total percentages, UNEB grades (D1-F9), competence remarks, and teacher comments.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Class marks roster retrieved",
  "data": {
    "max_scores": { "formative_max": 20.0, "summative_max": 80.0 },
    "students": [
      {
        "id": 8,
        "first_name": "Mukibi",
        "last_name": "Henry",
        "formative_score": 18.5,
        "summative_score": 73.5,
        "total_percentage": 92.0,
        "grade": "D1"
      }
    ]
  }
}
POST ?action=marks_save /academics/marks/save-bulk
Bearer Token

Bulk submit formative & summative scores. Computes total percentage, UNEB grade (D1-F9), competence remarks, and syncs report cards.

Request Payload:

{
  "term_id": 2,
  "class_id": 1,
  "subject_id": 1,
  "assessment_period": "end_of_term",
  "submit_action": "submit",
  "scores": {
    "8": {
      "formative_score": 18.5,
      "summative_score": 73.5,
      "teacher_comment": "Outstanding numerical skill",
      "competence_remark": "Demonstrates mastery"
    }
  }
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Academic marks saved successfully for 1 students!",
  "data": {
    "saved_count": 1,
    "status": "submitted"
  }
}
Module 7

Student Report Cards & Remarks

GET ?action=report_cards_summary&class_id=1&term_id=2 /report-cards/class-summary
Bearer Token

View class report cards status, percentages, grades, and parent publishing flags.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Class report cards status retrieved",
  "data": [
    {
      "id": 8,
      "admission_no": "ADM-008",
      "first_name": "Mukibi",
      "last_name": "Henry",
      "overall_percentage": "92.00",
      "overall_grade": "D1",
      "teacher_remarks": "Excellent student",
      "report_card_visible": 1
    }
  ]
}
POST ?action=report_cards_remarks /report-cards/save-remarks
Bearer Token

Save teacher remarks, headteacher remarks, and attendance days for a student report card.

Request Payload:

{
  "student_id": 8,
  "term_id": 2,
  "teacher_remarks": "Mukibi has demonstrated exceptional performance throughout the term.",
  "attendance_days_present": 62,
  "attendance_days_absent": 1
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Report card remarks saved successfully!",
  "data": null
}
Module 8

Student Gate Passes & Approvals

GET ?action=gate_passes_pending /gate-passes/pending
Bearer Token

List pending student gate passes requiring teacher approval.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Pending gate passes retrieved",
  "data": [
    {
      "id": 15,
      "pass_number": "GP-20260830-742",
      "reason": "Hospital Dental Appointment",
      "first_name": "Mukibi",
      "last_name": "Henry",
      "class_name": "Senior 1",
      "status": "pending"
    }
  ]
}
POST ?action=gate_pass_approve /gate-passes/approve
Bearer Token

Approve or reject student gate pass exit permission.

Request Payload:

{ "gate_pass_id": 15, "decision": "approve" }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Gate pass approved successfully!",
  "data": null
}
Module 9

Health & Clinic Reporting

POST ?action=health_report /health/report-incident
Bearer Token

Report sick student directly to the school infirmary. Notifies parent immediately.

Request Payload:

{
  "student_id": 8,
  "incident_type": "High Fever & Headache",
  "symptoms": "Shivering and complained of sharp head pain during lesson",
  "temperature_celsius": "38.7",
  "notes": "Sent to school infirmary with classroom prefect"
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Student clinic incident reported successfully!",
  "data": { "incident_id": 16 }
}
Module 10

Salary & Payslips

GET ?action=payroll_summary /payroll/summary
Bearer Token

Teacher's basic salary, allowances, deductions, and monthly salary disbursement history.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Teacher salary & payslip records retrieved",
  "data": {
    "salary_structure": {
      "basic_salary_ugx": "850000.00",
      "allowance_ugx": "150000.00",
      "net_salary_ugx": "1000000.00"
    },
    "payment_history": [
      {
        "id": 12,
        "amount_paid_ugx": "1000000.00",
        "payment_method": "Bank Transfer",
        "payment_date": "2026-08-28",
        "payment_month": "August 2026",
        "recorded_by_name": "Bursar Office"
      }
    ]
  }
}
Module 11

Assigned Classes & Students Directory

GET ?action=classes_assigned /classes/assigned
Bearer Token

List classes and streams assigned to this teacher with total student counts.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Assigned classes retrieved",
  "data": [
    { "id": 1, "class_name": "Senior 1", "total_students": 38 }
  ]
}
GET ?action=class_students&class_id=1 /classes/students
Bearer Token

Student roster in a class with student code, admission no, and parent contacts.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Class students roster retrieved",
  "data": [
    {
      "id": 8,
      "admission_no": "ADM-008",
      "first_name": "Mukibi",
      "last_name": "Henry",
      "gender": "Male",
      "parent_name": "Sarah Kimuli",
      "parent_phone": "0757755338"
    }
  ]
}
Module 12

Messaging & Staff Chat

GET ?action=chats /chats
Bearer Token

List teacher's support, staff, and parent chat conversation threads.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Teacher chats retrieved",
  "data": [
    {
      "id": 9,
      "ticket_number": "TCH-20260830-4912",
      "subject": "Lab Chemical Requisition",
      "last_message": "Chemistry practicals scheduled for Friday morning.",
      "unread_count": 0
    }
  ]
}
POST ?action=chat_create /chats/create
Bearer Token

Open a new inquiry or consultation chat ticket with School Admin or Parents.

Sample Response:

{
  "success": true,
  "status_code": 201,
  "message": "Chat ticket created successfully!",
  "data": { "chat_id": 9, "ticket_number": "TCH-20260830-4912" }
}
GET ?action=chat_messages&chat_id=9 /chats/messages
Bearer Token

Fetch conversation messages and automatically mark unread messages as read.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Chat messages retrieved",
  "data": {
    "chat": { "id": 9, "subject": "Lab Chemical Requisition" },
    "messages": [
      {
        "id": 41,
        "sender_name": "Mrs. Florence Nsubuga",
        "sender_role": "teacher",
        "message": "Please approve 500ml hydrochloric acid for S.1 lab session."
      }
    ]
  }
}
POST ?action=chat_send /chats/send
Bearer Token

Send message reply with optional file attachment.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Message sent successfully",
  "data": { "message_id": 42, "attachment_url": null }
}
Module 13

Circulars & Alerts

GET ?action=announcements&limit=20 /announcements
Bearer Token

List official school circulars and staff broadcast notices.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Announcements retrieved",
  "data": [
    {
      "id": 14,
      "title": "Staff General Assembly",
      "content": "All academic staff are requested to assemble in the main hall at 4:30 PM.",
      "created_at": "2026-08-30 08:00:00"
    }
  ]
}
GET ?action=notifications&unread_only=false /notifications
Bearer Token

Real-time notification feed with unread count and read receipts.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Notifications retrieved",
  "data": {
    "unread_count": 1,
    "notifications": [
      {
        "id": 35,
        "title": "Gate Pass Authorization",
        "message": "A new exit pass for Henry Mukibi requires your endorsement.",
        "is_read": 0
      }
    ]
  }
}
Module 14

Academic Calendar & Events

GET ?action=calendar_events&start_date=2026-08-01&end_date=2026-08-31 /calendar/events
Bearer Token

Scoped academic events: Term opening/closing, exams, staff briefings, sports days, and public holidays.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Calendar events retrieved",
  "data": [
    {
      "id": 5,
      "event_title": "End of Term UNEB Mock Examinations",
      "start_date": "2026-08-25",
      "end_date": "2026-08-29",
      "category": "academic"
    }
  ]
}
Module 15

Emergency & Safety Hotlines

GET ?action=emergency_alerts /emergency/alerts
Bearer Token

Active campus emergency alerts and security agency hotline contacts.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Emergency alerts retrieved",
  "data": {
    "active_incidents": [],
    "agency_contacts": [
      {
        "agency_name": "Uganda Police Patrol",
        "phone_number": "999 / 112",
        "agency_type": "Police"
      },
      {
        "agency_name": "City Ambulance Dispatch",
        "phone_number": "+256 800 111 000",
        "agency_type": "Medical"
      }
    ]
  }
}

SDK Code Examples

React Native / TypeScript Integration teacherApi.ts 
import axios from 'axios';

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

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

// 1. Teacher Login
export const loginTeacher = async (login: string, pin: string) => {
  const res = await teacherApi.post('&action=auth_login', { login, pin });
  if (res.data.success) {
    setTeacherAuthToken(res.data.data.token);
  }
  return res.data;
};

// 2. Submit Daily Morning Roll Call
export const submitRollCall = async (classId: number, streamId: number, attendance: Record) => {
  const res = await teacherApi.post('&action=rollcall_submit', {
    class_id: classId,
    stream_id: streamId,
    attendance,
  });
  return res.data;
};
Flutter / Dart Integration teacher_api_service.dart 
import 'dart:convert';
import 'package:http/http.dart' as http;

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

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

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

  // 1. Teacher Login
  Future<Map<String, dynamic>> login(String login, String pin) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=auth_login'),
      headers: _headers,
      body: jsonEncode({'login': login, 'password': pin}),
    );
    final data = jsonDecode(response.body);
    if (data['success'] == true) {
      _authToken = data['data']['token'];
    }
    return data;
  }

  // 2. GPS Gate Clock-In
  Future<Map<String, dynamic>> clockIn(double lat, double lng) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=attendance_clock_in'),
      headers: _headers,
      body: jsonEncode({'latitude': lat, 'longitude': lng}),
    );
    return jsonDecode(response.body);
  }
}