💼 Sales Person, Field Marketer & Growth Partner REST API

Sales Mobile App REST API

Official API reference for the EduPulse Sales Person & Growth Partner Mobile Application. Supports direct school onboarding from the field, CRM leads deal pipeline tracking, GPS pitch meeting check-ins, real-time 20% lifetime commission ledger, instant MTN/Airtel Mobile Money wallet withdrawals, dynamic WhatsApp promo link generator, marketing pitch deck repository, and gamification performance leaderboards.

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

Payload Format application/json (UTF-8)

Auth Header Authorization: Bearer <TOKEN>

Authentication & Security

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

// Example Sales Partner API Request Header
Authorization: Bearer e9b7c1029e8d475a1c2b3e4f5061728394a5b6c7d8e9f0123456789abcdef012
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 / 400 Bad Request)

{
  "success": false,
  "status_code": 422,
  "message": "school_name, district, phone, and admin_email are required.",
  "data": null,
  "errors": null
}

Module 1

Authentication & Sales Partner Profile

POST ?action=auth_login /auth/login

Public

Authenticates sales agent, partner director, or field marketer using agent code/phone/email and PIN or password.

Request Payload:

{
  "login": "AGT-KLA-101",
  "password": "1234"
}

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Sales agent login successful. Welcome to the EduPulse Growth & Partner Portal!",
  "data": {
    "token": "e9b7c1029e8d475a1c2b3e4f5061728394a5b6c7d8e9f0123456789abcdef012",
    "user": {
      "id": 25,
      "name": "Joseph Mukasa (EduPulse Partner)",
      "email": "agent@edupulse.ac.ug",
      "phone": "0772888999",
      "role_id": 10,
      "role_name": "agent",
      "agent_code": "AGT-KLA-101",
      "wallet_balance_ugx": "172745.00",
      "tier_level": "Silver Partner"
    },
    "agent": {
      "id": 1,
      "agent_code": "AGT-KLA-101",
      "full_name": "Joseph Mukasa (EduPulse Partner)",
      "commission_rate_percent": "20.00",
      "wallet_balance_ugx": "172745.00",
      "tier_level": "Silver Partner"
    }
  }
}

POST ?action=auth_forgot_password /auth/forgot-password

Public

Request Payload:

{ "login": "0772888999" }

Sample Response (`200 OK`):

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

POST ?action=auth_reset_password /auth/reset-password

Public

Request Payload:

{ "login": "0772888999", "otp_code": "7412", "new_password": "4321" }

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Password reset successfully! You are now logged in.",
  "data": { "token": "e9b7c1029e8d475a1c2b3e4f5061728394a5b6c7d8e9f0123456789abcdef012", "user": { "id": 25, "name": "Joseph Mukasa" } }
}

POST ?action=auth_logout /auth/logout

Bearer Token

Sample Response (`200 OK`):

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

GET ?action=profile /profile

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Sales Agent profile retrieved",
  "data": {
    "user": {
      "id": 25,
      "name": "Joseph Mukasa",
      "email": "agent@edupulse.ac.ug",
      "phone": "0772888999"
    },
    "agent": {
      "id": 1,
      "agent_code": "AGT-KLA-101",
      "full_name": "Joseph Mukasa",
      "phone": "0772888999",
      "commission_rate_percent": "20.00",
      "wallet_balance_ugx": "172745.00",
      "total_earned_ugx": "272745.00",
      "tier_level": "Silver Partner"
    },
    "stats": {
      "referred_schools": 2,
      "total_commission_ugx": 22745.00,
      "available_wallet_ugx": 172745.00,
      "commission_rate_percent": 20.00
    }
  }
}

POST ?action=profile_update /profile/update

Bearer Token

Request Payload:

{
  "full_name": "Joseph Mukasa",
  "phone": "0772888999",
  "payout_phone": "0772888999",
  "payout_name": "Joseph Mukasa (MTN MOMO)",
  "bank_name": "Stanbic Bank Uganda"
}

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Sales Partner profile updated successfully!",
  "data": {
    "agent": {
      "id": 1,
      "full_name": "Joseph Mukasa",
      "payout_phone": "0772888999",
      "payout_name": "Joseph Mukasa (MTN MOMO)"
    }
  }
}

GET ?action=agent_badge /agent-badge

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Sales Partner digital badge retrieved",
  "data": {
    "agent": {
      "id": 1,
      "agent_code": "AGT-KLA-101",
      "full_name": "Joseph Mukasa",
      "role": "Certified Growth Partner & Sales Ambassador",
      "tier_level": "Silver Partner",
      "commission_rate_percent": 20.00,
      "phone": "0772888999"
    },
    "company": "EduPulse Uganda & Africa",
    "barcode_data": "AGT-KLA-101",
    "qr_string": "EDUPULSE-AGENT:1:AGT-KLA-101:20PERCENT",
    "referral_url": "http://localhost/edupulse/index.php?page=register_school&ref=AGT-KLA-101"
  }
}

Module 2

Sales Executive KPI Census & Dashboard

GET ?action=dashboard /dashboard

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Sales executive KPI dashboard census retrieved",
  "data": {
    "metrics": {
      "wallet_balance_ugx": 172745.00,
      "total_lifetime_earned": 272745.00,
      "total_withdrawn_ugx": 100000.00,
      "pending_withdrawal_ugx": 0.00,
      "commission_rate_percent": 20.00,
      "referred_schools_count": 2,
      "total_enrolled_students": 9,
      "active_leads_in_pipeline": 1,
      "agent_tier": "Silver Partner"
    },
    "recent_commissions": [
      {
        "id": 8,
        "school_name": "Zana Mixed Secondary School",
        "school_code": "SCH-KMP-001",
        "transaction_type": "SMS Purchase",
        "transaction_amount_ugx": "675.00",
        "commission_rate_percent": "20.00",
        "commission_amount_ugx": "135.00",
        "status": "Earned",
        "created_at": "2026-08-16 22:46:31"
      }
    ],
    "recent_schools": [
      {
        "id": 1,
        "name": "Zana Mixed Secondary School",
        "school_code": "SCH-KMP-001",
        "district": "Kampala",
        "student_count": 9,
        "total_commission_from_school": "22745.00"
      }
    ],
    "referral_url": "http://localhost/edupulse/index.php?page=register_school&ref=AGT-KLA-101"
  }
}

Module 3

Universal 4-in-1 Sales Barcode/QR Scanner

POST ?action=scan_barcode /scan/barcode

Bearer Token

Scans school code/QR, promo voucher, or partner badge.

Request Payload (School Code):

{
  "scanned_code": "SCH-KMP-001"
}

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "School verified: Zana Mixed Secondary School",
  "data": {
    "entity_type": "school",
    "school": {
      "id": 1,
      "school_code": "SCH-KMP-001",
      "name": "Zana Mixed Secondary School",
      "district": "Kampala",
      "status": "active",
      "student_count": 9,
      "my_commission_earned": "22745.00"
    },
    "is_referred_by_me": true,
    "commission_earned": 22745.00
  }
}

Module 4

Direct School Onboarding Engine

POST ?action=school_onboard /schools/onboard

Bearer Token

Request Payload:

{
  "school_name": "St. Peters Senior Secondary School Nsambya",
  "district": "Kampala",
  "phone": "+256772111222",
  "email": "info@stpetersnsambya.sc.ug",
  "admin_name": "Brother Charles Lwanga (Headmaster)",
  "admin_email": "headmaster@stpetersnsambya.sc.ug",
  "address": "Ggaba Road, Nsambya Hill",
  "level_category": "Secondary",
  "ownership_type": "Private"
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "School St. Peters Senior Secondary School Nsambya successfully onboarded under your partner code (AGT-KLA-101)!",
  "data": {
    "school_id": 6,
    "school_code": "SCH-KAM-482",
    "school_name": "St. Peters Senior Secondary School Nsambya",
    "status": "pending_activation",
    "login_email": "headmaster@stpetersnsambya.sc.ug"
  }
}

GET ?action=referred_schools&status=active /schools/referred-list

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Referred schools portfolio retrieved",
  "data": [
    {
      "id": 1,
      "school_code": "SCH-KMP-001",
      "name": "Zana Mixed Secondary School",
      "district": "Kampala",
      "status": "active",
      "student_count": 9,
      "total_commission_from_school": "22745.00"
    }
  ]
}

Module 5

CRM Leads Pipeline & Deal Tracker

GET ?action=leads&stage=Demo Scheduled /leads/list

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "CRM sales leads pipeline retrieved",
  "data": [
    {
      "id": 1,
      "school_name": "Kampala Model Secondary School",
      "contact_person": "Dr. James Byaruhanga (Director)",
      "phone": "+256701555666",
      "district": "Wakiso",
      "stage": "Demo Scheduled",
      "deal_size_ugx": "2500000.00",
      "probability_percent": 60
    }
  ]
}

POST ?action=lead_create /leads/create

Bearer Token

Request Payload:

{
  "school_name": "Seeta High School Green Campus",
  "contact_person": "Mrs. Allen Namubiru (Headmistress)",
  "phone": "+256772445566",
  "district": "Mukono",
  "estimated_students": 1200,
  "stage": "New",
  "deal_size_ugx": 4440000
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "Sales lead for Seeta High School Green Campus logged successfully!",
  "data": { "lead_id": 2, "school_name": "Seeta High School Green Campus", "stage": "New" }
}

Module 6

Field Sales Visits & Meeting Check-In (GPS)

POST ?action=visit_check_in /visits/check-in

Bearer Token

Request Payload:

{
  "school_name": "Seeta High School Green Campus",
  "lead_id": 2,
  "visit_type": "System Demo",
  "latitude": 0.3582,
  "longitude": 32.7481,
  "location_address": "Seeta, Mukono District",
  "contact_person_met": "Mrs. Allen Namubiru (Headmistress)",
  "summary_notes": "Presented 30-min demo on O-Level CBC assessment and UNEB grading.",
  "outcome": "Proposal Requested"
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "GPS Field Visit logged at Seeta High School Green Campus successfully!",
  "data": { "visit_id": 1, "school_name": "Seeta High School Green Campus", "timestamp": "2026-08-30 16:30:00" }
}

Module 7

Commission Earnings Ledger & Breakdown

GET ?action=commission_ledger&limit=50 /commissions/ledger

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Commission earnings ledger retrieved",
  "data": {
    "total_commission_ugx": 22745.00,
    "ledger": [
      {
        "id": 8,
        "school_name": "Zana Mixed Secondary School",
        "transaction_type": "SMS Purchase",
        "transaction_amount_ugx": "675.00",
        "commission_rate_percent": "20.00",
        "commission_amount_ugx": "135.00",
        "status": "Earned",
        "created_at": "2026-08-16 22:46:31"
      }
    ]
  }
}

Module 8

MOMO Instant Wallet & Commission Withdrawals

POST ?action=wallet_withdraw /wallet/withdraw

Bearer Token

Request Payload:

{
  "amount_ugx": 50000,
  "payout_phone": "0772888999",
  "payout_name": "Joseph Mukasa (MTN MOMO)"
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "Withdrawal request of UGX 50,000 submitted successfully! SuperAdmin will disburse to 0772888999.",
  "data": {
    "withdrawal_id": 1,
    "reference": "AGT-WD-20260830-163512-841",
    "amount_ugx": 50000,
    "status": "Pending"
  }
}

Module 9

Dynamic Referral Links & WhatsApp Share

GET ?action=referral_links /referrals/links

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Dynamic sales partner referral links generated",
  "data": {
    "agent_code": "AGT-KLA-101",
    "referral_url": "http://localhost/edupulse/index.php?page=register_school&ref=AGT-KLA-101",
    "whatsapp_share_url": "https://api.whatsapp.com/send?text=Hello!+Register+your+school...",
    "commission_rate": "20% Lifetime"
  }
}

Module 10

Pitch Deck, Demos & Sales Collateral Repository

GET ?action=marketing_materials /marketing/materials

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Sales pitch collateral & marketing repository retrieved",
  "data": [
    {
      "id": 1,
      "title": "EduPulse Africa Official System Pitch Deck 2026",
      "category": "Pitch Deck",
      "file_url": "assets/docs/edupulse_pitch_deck_2026.pdf",
      "file_size_mb": "4.50"
    }
  ]
}

Module 11

Sales Targets, Milestones & Leaderboard

GET ?action=leaderboard /gamification/leaderboard

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Top sales partners leaderboard retrieved",
  "data": [
    {
      "id": 1,
      "agent_code": "AGT-KLA-101",
      "full_name": "Joseph Mukasa",
      "tier_level": "Silver Partner",
      "schools_onboarded_count": 2,
      "total_commission_ugx": "22745.00"
    }
  ]
}

Module 12

In-App Sales Support & Head Office Chat

GET ?action=chats /chats

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Sales support & Head Office communication threads retrieved",
  "data": [
    {
      "id": 16,
      "ticket_number": "SALES-20260830-8819",
      "subject": "Custom Multi-Campus Pricing for Seeta High",
      "status": "open"
    }
  ]
}

Module 13

Circulars, Bulletins & Commission Alerts

GET ?action=notifications /notifications

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Partner notifications retrieved",
  "data": {
    "unread_count": 1,
    "notifications": [
      {
        "id": 70,
        "title": "Commission Credited! +UGX 135",
        "message": "Zana Mixed Secondary School purchased 500 SMS units.",
        "is_read": 0
      }
    ]
  }
}

Module 14

Academic Calendar & School Sales Seasons

GET ?action=calendar_events&start_date=2026-08-01&end_date=2026-11-30 /calendar/events

Bearer Token

Sample Response (`200 OK`):

{
  "success": true,
  "status_code": 200,
  "message": "Academic calendar & school sales seasons retrieved",
  "data": [
    {
      "id": 10,
      "title": "Term 3 National School Reopening (Peak Buying Period)",
      "start_date": "2026-09-15",
      "end_date": "2026-09-22",
      "event_type": "Sales Season"
    }
  ]
}

Module 15

Emergency Field Support & Fraud Escalation

POST ?action=emergency_report_issue /emergency/report-issue

Escalation Desk

Request Payload:

{
  "issue_type": "School Lead Conflict / Impersonation",
  "details": "A third-party agent claimed commission on Seeta High School despite my prior registered field visit."
}

Sample Response (`201 Created`):

{
  "success": true,
  "status_code": 201,
  "message": "Emergency escalation dispatched to SuperAdmin & Legal Counsel.",
  "data": { "escalation_id": 95, "status": "Under Review" }
}

SDK Code Examples

React Native / TypeScript Integration salesApi.ts

import axios from 'axios';

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

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

// 1. Onboard School Directly
export const onboardSchool = async (payload: {
  school_name: string;
  district: string;
  phone: string;
  admin_email: string;
  admin_name?: string;
  level_category?: string;
}) => {
  const res = await salesApi.post('&action=school_onboard', payload);
  return res.data;
};

// 2. Request Mobile Money Withdrawal
export const requestWithdrawal = async (amountUgx: number, payoutPhone: string, payoutName: string) => {
  const res = await salesApi.post('&action=wallet_withdraw', {
    amount_ugx: amountUgx,
    payout_phone: payoutPhone,
    payout_name: payoutName
  });
  return res.data;
};

Flutter / Dart Integration sales_api_service.dart

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

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

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

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

  // 1. Universal Sales Barcode Scanner
  Future<Map<String, dynamic>> scanBarcode(String code) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=scan_barcode'),
      headers: _headers,
      body: jsonEncode({'scanned_code': code}),
    );
    return jsonDecode(response.body);
  }

  // 2. Onboard School Directly
  Future<Map<String, dynamic>> onboardSchool(Map<String, dynamic> payload) async {
    final response = await http.post(
      Uri.parse('$baseUrl&action=school_onboard'),
      headers: _headers,
      body: jsonEncode(payload),
    );
    return jsonDecode(response.body);
  }
}