⚡ Complete Driver REST API Specification

Driver Mobile App REST API

Official API specification for the EduPulse Driver Mobile Application. Supports real-time morning/afternoon passenger manifest tracking (with automatic parent SMS alerts upon boarding & drop-off), trip start/end management, fuel logging, maintenance reporting, shift GPS check-in, and one-tap roadside emergency dispatch.

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

Payload Format application/json (UTF-8)

Auth Header Authorization: Bearer <TOKEN>

Authentication & Security

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

// Example Driver API Request Header
Authorization: Bearer 50b48a5bec5bf76b9271757b77348e3310a4aed31052d69874471f4c5f295e67
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 (409 Conflict / 422 Unprocessable)

{
  "success": false,
  "status_code": 409,
  "message": "You already have an active trip in transit!",
  "data": null,
  "errors": null
}

Module 1

Authentication & Driver Profile

POST ?action=auth_login /auth/login

Public

Authenticates driver using phone/email and PIN or password. Returns Bearer token, driver details, assigned vehicle, and route.

Request Payload:

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

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Driver login successful. Welcome on board!",
  "data": {
    "token": "50b48a5bec5bf76b9271757b77348e3310a4aed31052d69874471f4c5f295e67",
    "user": {
      "id": 18,
      "name": "Tr. Samuel Katende",
      "email": "driver@stjulian.edu.ug",
      "phone": "+256 772 100 200",
      "role_id": 8,
      "role_name": "driver",
      "school_name": "St. Julian High School"
    },
    "driver": {
      "id": 1,
      "driver_code": "DRV-2026-001",
      "license_number": "DL-UG-99412",
      "assigned_vehicle_number": "UBA 452K (Bus 1)",
      "assigned_route_name": "Ntinda - Kisaasi Route"
    }
  }
}

POST ?action=auth_forgot_password /auth/forgot-password

Public

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

Request Payload:

{ "login": "+256772100200" }

Sample Response:

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

POST ?action=auth_reset_password /auth/reset-password

Public

Verifies OTP code and updates driver PIN, returning new active Bearer token.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Password reset successfully! You are now logged in.",
  "data": {
    "token": "a1b2c3d4e5f67890123456789abcdef1234567890abcdef1234567890abcdef",
    "user": { "id": 18, "name": "Tr. Samuel Katende" }
  }
}

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 driver profile, license details, and assigned vehicle/route information.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Driver profile retrieved",
  "data": {
    "user": {
      "id": 18,
      "name": "Tr. Samuel Katende",
      "email": "driver@stjulian.edu.ug",
      "phone": "+256 772 100 200",
      "photo_url": "uploads/drivers/drv_1.jpg"
    },
    "driver": {
      "id": 1,
      "driver_code": "DRV-2026-001",
      "license_number": "DL-UG-99412",
      "assigned_vehicle_number": "UBA 452K (Bus 1)",
      "assigned_route_name": "Ntinda - Kisaasi Route"
    }
  }
}

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": 18,
      "name": "Tr. Samuel Katende",
      "photo_url": "uploads/drivers/drv_1784620000_123.jpg"
    }
  }
}

GET ?action=driver_badge /driver-badge

Bearer Token

Digital Driver ID badge payload with barcode and QR string for checkpoint scanning.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Driver digital badge payload retrieved",
  "data": {
    "driver": {
      "id": 1,
      "driver_code": "DRV-2026-001",
      "name": "Tr. Samuel Katende",
      "license_number": "DL-UG-99412",
      "assigned_vehicle_number": "UBA 452K (Bus 1)",
      "assigned_route_name": "Ntinda - Kisaasi Route"
    },
    "barcode_data": "DRV-2026-001",
    "qr_string": "EDUPULSE-DRIVER:1:DRV-2026-001:SCH-1"
  }
}

Module 2

Driver Dashboard & Trip Overview

GET ?action=dashboard /dashboard

Bearer Token

Real-time driver dashboard overview with active trip status, passenger manifest, completed trips count, and assigned bus details.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Driver dashboard overview retrieved",
  "data": {
    "driver": {
      "id": 1,
      "name": "Tr. Samuel Katende",
      "assigned_vehicle_number": "UBA 452K (Bus 1)",
      "assigned_route_name": "Ntinda - Kisaasi Route"
    },
    "trip_status": {
      "is_in_transit": true,
      "active_trip": {
        "id": 5,
        "trip_type": "Afternoon Drop-off (School to Home)",
        "vehicle_number": "UBA 452K (Bus 1)",
        "route_name": "Ntinda - Kisaasi Route",
        "start_time": "2026-08-30 15:43:40",
        "status": "In Transit"
      },
      "passenger_manifest": [
        {
          "student_id": 8,
          "student_name": "Mukibi Henry",
          "class_name": "Senior 1",
          "status": "Boarded",
          "parent_phone": "0757755338"
        }
      ],
      "today_completed_trips": 1,
      "assigned_students_count": 14
    },
    "unread_notifications": 2,
    "open_chats": 1
  }
}

Module 3

Live Trips & Passenger Tracking

POST ?action=trip_start /trips/start

Bearer Token

Start Morning Pick-up or Afternoon Drop-off. Automatically sends real-time SMS alerts to all linked parents.

Request Payload:

{
  "trip_type": "Morning Pick-up",
  "vehicle_number": "UBA 452K (Bus 1)",
  "route_name": "Ntinda - Kisaasi Route",
  "driver_notes": "Departing school gate",
  "selected_student_ids": [8, 10, 14, 18]
}

Sample Response:

{
  "success": true,
  "status_code": 201,
  "message": "Transport trip started successfully (Morning Pick-up - 4 passengers on board). SMS alerts sent to parents.",
  "data": {
    "trip_id": 6,
    "trip_type": "Morning Pick-up",
    "status": "In Transit",
    "start_time": "2026-08-30 06:45:00",
    "passenger_count": 4
  }
}

GET ?action=trip_active /trips/active

Bearer Token

Get active in-transit trip details and live passenger status manifest.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Active transport trip retrieved",
  "data": {
    "trip": {
      "id": 6,
      "trip_type": "Morning Pick-up",
      "vehicle_number": "UBA 452K (Bus 1)",
      "route_name": "Ntinda - Kisaasi Route",
      "start_time": "2026-08-30 06:45:00",
      "status": "In Transit"
    },
    "passenger_manifest": [
      {
        "student_id": 8,
        "student_name": "Mukibi Henry",
        "class_name": "Senior 1",
        "status": "Pending",
        "parent_phone": "0757755338"
      }
    ]
  }
}

POST ?action=trip_update_student /trips/update-student

Bearer Token

Mark passenger as Boarded, Dropped Off, or Absent. Instantly fires parent SMS notification.

Request Payload:

{
  "trip_id": 6,
  "student_id": 8,
  "status": "Boarded",
  "location_note": "Kisaasi Total Station Stage"
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Student passenger status updated to 'Boarded' (Parent notified via SMS)!",
  "data": {
    "student_id": 8,
    "status": "Boarded",
    "timestamp": "2026-08-30 07:12:35"
  }
}

POST ?action=trip_bulk_update /trips/bulk-update

Bearer Token

Bulk mark all passengers on the active trip as Boarded or Dropped Off.

Request Payload:

{ "trip_id": 6, "bulk_action": "drop_off_all" }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Bulk status complete: Marked 4 students as 'Dropped Off'!",
  "data": { "trip_id": 6, "target_status": "Dropped Off", "marked_count": 4 }
}

POST ?action=trip_end /trips/end

Bearer Token

Finish and complete active trip, logging ending odometer notes.

Request Payload:

{ "trip_id": 6, "closing_notes": "All learners dropped safely at school main gate." }

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Transport trip completed and logged successfully!",
  "data": { "trip_id": 6, "status": "Completed", "end_time": "2026-08-30 07:55:00" }
}

GET ?action=trips_history&limit=20 /trips/history

Bearer Token

Fetch previous transport trips with passenger counts and completion times.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Transport trips history retrieved",
  "data": [
    {
      "id": 5,
      "trip_date": "2026-08-30",
      "trip_type": "Morning Pick-up",
      "vehicle_number": "UBA 452K (Bus 1)",
      "boarded_count": 14,
      "status": "Completed"
    }
  ]
}

Module 4

Driver GPS Shift Attendance

POST ?action=attendance_clock_in /attendance/clock-in

Bearer Token

Shift clock-in / clock-out with GPS coordinates and device tracking.

Request Payload:

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

Sample Response:

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

GET ?action=attendance_history&limit=30 /attendance/history

Bearer Token

Past 30-100 days driver shift attendance records.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Driver attendance logs retrieved",
  "data": [
    { "date": "2026-08-30", "check_in_time": "06:15:00", "check_out_time": "18:00:00", "status": "present" }
  ]
}

Module 5

Assigned Bus Routes & Passengers Directory

GET ?action=routes_assigned /routes/assigned

Bearer Token

View transport routes, bus stops, and pickup windows assigned to this driver.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Assigned transport routes retrieved",
  "data": [
    {
      "route_name": "Ntinda - Kisaasi Route",
      "vehicle_number": "UBA 452K (Bus 1)",
      "morning_pickup": "06:30 AM - 07:45 AM",
      "major_stops": ["Ntinda Market", "Kisaasi Total", "School Gate"]
    }
  ]
}

GET ?action=routes_passengers /routes/passengers

Bearer Token

List of all students registered on the route with guardian names and phone numbers.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Route passenger students roster retrieved",
  "data": [
    {
      "id": 8,
      "admission_no": "ADM-008",
      "first_name": "Mukibi",
      "last_name": "Henry",
      "class_name": "Senior 1",
      "parent_name": "Sarah Kimuli",
      "parent_phone": "0757755338"
    }
  ]
}

Module 6

Vehicle Health, Fuel Logging & Maintenance

GET ?action=vehicle_details /vehicle/details

Bearer Token

Assigned bus specifications, roadworthiness status, seating capacity, and insurance expiry.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Assigned vehicle details retrieved",
  "data": {
    "vehicle_number": "UBA 452K (School Bus 1)",
    "model": "Isuzu NPR 35-Seater Bus",
    "seating_capacity": 35,
    "insurance_status": "Valid (Expires 31 Dec 2026)",
    "speed_governor": "Active / 60 km/h Calibrated"
  }
}

POST ?action=vehicle_log_fuel /vehicle/log-fuel

Bearer Token

Record fuel refill details including liters, cost in UGX, and current odometer reading.

Request Payload:

{
  "liters": 45.5,
  "cost_ugx": 250000,
  "odometer_km": 142850,
  "fuel_station": "TotalEnergies Ntinda"
}

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Fuel refill logged successfully!",
  "data": {
    "liters": 45.5,
    "cost_ugx": 250000,
    "odometer_km": 142850,
    "logged_at": "2026-08-30 11:30:00"
  }
}

POST ?action=vehicle_report_issue /vehicle/report-issue

Bearer Token

Report mechanical defect or servicing requirement to the school transport officer.

Request Payload:

{
  "issue_type": "Braking System Check",
  "urgency": "high",
  "description": "Brake pads making screeching sound when stopping."
}

Sample Response:

{
  "success": true,
  "status_code": 201,
  "message": "Vehicle maintenance report submitted to transport manager!",
  "data": { "ticket_number": "VEH-20260830-412", "urgency": "high" }
}

Module 7

Salary & Route Allowances

GET ?action=payroll_summary /payroll/summary

Bearer Token

Driver basic salary, route allowances, trip bonuses, and monthly payment vouchers.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Driver wage & payslip records retrieved",
  "data": {
    "salary_structure": {
      "basic_salary_ugx": "650000.00",
      "allowance_ugx": "100000.00",
      "net_salary_ugx": "750000.00"
    },
    "payment_history": [
      {
        "id": 4,
        "amount_paid_ugx": "750000.00",
        "payment_method": "Mobile Money",
        "payment_date": "2026-08-28"
      }
    ]
  }
}

Module 8

Messaging & Staff Chat

GET ?action=chats /chats

Bearer Token

List driver communication channels with transport administration.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Driver chats retrieved",
  "data": [
    {
      "id": 9,
      "ticket_number": "DRV-20260830-4912",
      "subject": "Heavy Traffic Delay Notice",
      "last_message": "Northern bypass traffic cleared. Proceeding to Kisaasi."
    }
  ]
}

Module 9

Circulars & Alerts

GET ?action=notifications /notifications

Bearer Token

Real-time driver alerts, route changes, weather warnings, and school announcements.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Notifications retrieved",
  "data": {
    "unread_count": 0,
    "notifications": [
      {
        "id": 19,
        "title": "Route Diversion Alert",
        "message": "Road works along Ntinda Stretcher. Use Bukoto flyover."
      }
    ]
  }
}

Module 10

Academic Calendar & Transport Schedule

GET ?action=calendar_events /calendar/events

Bearer Token

Term opening dates, early dismissals, visitation days, and sports shuttle schedules.

Sample Response:

{
  "success": true,
  "status_code": 200,
  "message": "Calendar events retrieved",
  "data": [
    { "id": 4, "event_title": "End of Term Bus Pick-up (12:00 PM)", "start_date": "2026-08-31" }
  ]
}

Module 11

Roadside Emergency & Hotlines

POST ?action=emergency_panic /emergency/panic-report

SOS Dispatch

One-tap emergency broadcast triggered by driver during an active transport trip (Accident, Mechanical, Medical).

Request Payload:

{
  "emergency_type": "Road Accident / Collision",
  "current_location": "Bukoto-Kisaasi Road near Northern Bypass flyover",
  "latitude": 0.3541,
  "longitude": 32.5912,
  "notes": "Minor bump by taxi. All learners safe inside bus."
}

Sample Response:

{
  "success": true,
  "status_code": 201,
  "message": "Roadside emergency broadcast dispatched to school administration and transport safety dispatchers!",
  "data": {
    "incident_id": 7,
    "emergency_type": "Road Accident / Collision",
    "status": "Dispatched"
  }
}

GET ?action=emergency_alerts /emergency/alerts

Bearer Token

Emergency service hotlines: Police Patrol, Traffic Dispatch, Ambulance, and Towing Services.

Sample Response:

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

SDK Code Examples

React Native / TypeScript Integration driverApi.ts

import axios from 'axios';

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

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

// 1. Driver Login
export const loginDriver = async (login: string, pin: string) => {
  const res = await driverApi.post('&action=auth_login', { login, password: pin });
  if (res.data.success) {
    setDriverAuthToken(res.data.data.token);
  }
  return res.data;
};

// 2. Start Transport Route
export const startRouteTrip = async (tripType: string, selectedStudents: number[]) => {
  const res = await driverApi.post('&action=trip_start', {
    trip_type: tripType,
    selected_student_ids: selectedStudents,
  });
  return res.data;
};

// 3. Mark Student Boarded
export const markStudentBoarded = async (tripId: number, studentId: number, stopName: string) => {
  const res = await driverApi.post('&action=trip_update_student', {
    trip_id: tripId,
    student_id: studentId,
    status: 'Boarded',
    location_note: stopName,
  });
  return res.data;
};

Flutter / Dart Integration driver_api_service.dart

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

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

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

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

  // 1. Driver 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. Start Transport Trip
  Future<Map<String, dynamic>> startTrip(String tripType, List<int> studentIds) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=trip_start'),
      headers: _headers,
      body: jsonEncode({
        'trip_type': tripType,
        'selected_student_ids': studentIds,
      }),
    );
    return jsonDecode(response.body);
  }
}