TerraGo API

Reports

Operational and business analytics. Attendance reporting (average, trends, absentees, late arrivals, best on-time zone/location), route and fleet efficiency, admin/org-wide dashboard metrics and report-schedule settings, plus PDF/Excel exports delivered asynchronously by email.

17 endpoint(s)

Route Reports

GET Get Route Analysis Stats Route Reports {{url}}/reports/route-analysis/stats ▸

High-level route KPIs for a dashboard: how many routes are critically delayed, which route carries the highest daily volume, and average route duration — each compared against the prior period of equal length.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional, default 30d): Shorthand alternative to date_range — 7d, 30d, or 90d.

Response

Includes criticaldelays (routes running more than 15 minutes late), highestvolume (route name/id + avg students per day), and avgroutetime (minutes, with delta vs. the prior period).

Notes

  • Scoped to routes tagged under your account.
Auth
Bearer token
Request Body
{
    "date_range": "2026-04-01,2026-04-30"  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "period": {
            "from": "2026-04-01",
            "to": "2026-04-30"
        },
        "critical_delays": {
            "value": 5,
            "description": "Routes with >15m lag"
        },
        "highest_volume": {
            "route_name": "PM_School Ruiru - Migaa Route Route",
            "route_id": "b64722e9-2c41-4feb-a9e6-d27774263557",
            "avg_students_per_day": 65
        },
        "avg_route_time": {
            "value_minutes": 87,
            "delta_minutes": -163,
            "previous_minutes": 250
        }
    },
    "message": "Route analysis stats retrieved successfully"
}
GET Get Route Ranking Route Reports {{url}}/reports/route-analysis/ranking ▸

Paginated ranking of routes by how delayed/risky they are, with per-route trip volume and timing stats.

Query Parameters

  • date_range / period (see Get Route Analysis Stats)
  • per_page (integer, optional, default 15, max 50)
  • search (string, optional): Matches route name.
  • alert_risk (string, optional): Filter to HIGH, MEDIUM, or LOW risk routes.

Notes

  • Risk is computed from average delay vs. each route's own alert_settings thresholds (default: HIGH if delay > 15 min, MEDIUM if > 8 min, else LOW).
  • Sorted by average delay, worst first.

Response

Paginated ranking of routes (data) with meta; each: route, average delay, trip volume and alert_risk.

Auth
Bearer token
Request Body
{
    "date_range": "2026-04-01,2026-04-30",
    // "alert_risk": "HIGH",  //use MEDIUM, LOW
    // "search": "Ruiru",
    "page": 1,
    "per_page": 15
}
Sample Response (200 OK)
{
    "data": [
        {
            "route": {
                "id": "ed04d036-cb6e-4235-b77c-df6314cc503d",
                "name": "PM_School Kitusuru Route"
            },
            "total_students": 1,
            "avg_students_per_day": 1,
            "avg_actual_minutes": 2121,
            "est_duration_minutes": 10,
            "avg_delay_minutes": 2111,
            "alert_risk": "HIGH",
            "trip_count": 2,
            "active_days": 1
        },
        {
            "route": {
                "id": "b64722e9-2c41-4feb-a9e6-d27774263557",
                "name": "PM_School Ruiru - Migaa Route Route"
            },
            "total_students": 654,
            "avg_students_per_day": 65,
            "avg_actual_minutes": 368,
            "est_duration_minutes": 15,
            "avg_delay_minutes": 353,
            "alert_risk": "HIGH",
            "trip_count": 29,
            "active_days": 10
        },
        {
            "route": {
                "id": "705cd624-c5b8-44b6-8577-67c7edbcdcbc",
                "name": "PM_School Mombasa Road Route"
            },
            "total_students": 0,
            "avg_students_per_day": 0,
            "avg_actual_minutes": 197,
            "est_duration_minutes": 30,
            "avg_delay_minutes": 167,
            "alert_risk": "HIGH",
            "trip_count": 14,
            "active_days": 6
        },
        {
            "route": {
                "id": "bc49432a-c179-4df7-abc1-8b247a149289",
                "name": "Kenya_High_School South C Route"
            },
            "total_students": 378,
            "avg_students_per_day": 32,
            "avg_actual_minutes": 188,
            "est_duration_minutes": 30,
            "avg_delay_minutes": 158,
            "alert_risk": "HIGH",
            "trip_count": 55,
            "active_days": 12
        },
        {
            "route": {
                "id": "e858014f-d118-40db-a54e-1a5956441bd3",
                "name": "PM_School Office to Langata Route"
            },
            "total_students": 38,
            "avg_students_per_day": 4,
            "avg_actual_minutes": 103,
            "est_duration_minutes": 30,
            "avg_delay_minutes": 73,
            "alert_risk": "HIGH",
            "trip_count": 19,
            "active_days": 9
        },
        {
            "route": {
                "id": "7798a742-aa9d-4ab3-bde2-981720df3296",
                "name": "Kiota_School Updated Route"
            },
            "total_students": 0,
            "avg_students_per_day": 0,
            "avg_actual_minutes": 39,
            "est_duration_minutes": 45,
            "avg_delay_minutes": -6,
            "alert_risk": "LOW",
            "trip_count": 1,
            "active_days": 1
        },
        {
            "route": {
                "id": "2241ff88-f590-4fb1-9b99-18ecf15cfc82",
                "name": "PM_School Thika Road Route"
            },
            "total_students": 232,
            "avg_students_per_day": 12,
            "avg_actual_minutes": -181,
            "est_duration_minutes": 30,
            "avg_delay_minutes": -211,
            "alert_risk": "LOW",
            "trip_count": 73,
            "active_days": 19
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8000/api/reports/route-analysis/ranking?page=1",
        "last": "http://127.0.0.1:8000/api/reports/route-analysis/ranking?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/route-analysis/ranking?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "http://127.0.0.1:8000/api/reports/route-analysis/ranking",
        "per_page": 15,
        "to": 7,
        "total": 7,
        "period": {
            "from": "2026-04-01",
            "to": "2026-04-30"
        }
    },
    "status": 200,
    "message": "Route ranking retrieved successfully"
}

Fleet Reports

GET Get Fleet Efficiency Stats Fleet Reports {{url}}/reports/fleet-efficiency/stats ▸

Fleet-wide cost and performance KPIs — total cost (fuel + maintenance), average fuel efficiency, average utilization, and average cost per student — each with a delta vs. the prior period.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional, default 30d): 7d, 30d, or 90d.

Notes

  • Scoped to the drivers/vehicles under your supervision.

Response

Fleet KPIs (data): total cost, average fuel efficiency, average utilization and average cost per student — each with a delta vs the prior period (KES).

Auth
Bearer token
Request Body
{
    "date_range": "2026-01-01,2026-04-30"  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "period": {
            "from": "2026-04-01",
            "to": "2026-04-30"
        },
        "total_fleet_cost": {
            "value": 13300,
            "fuel": 12300,
            "maintenance": 1000,
            "delta": -30120,
            "delta_pct": -69.4,
            "currency": "KES"
        },
        "avg_fuel_efficiency": {
            "value": null,
            "unit": "KM/L",
            "delta": null,
            "previous": 9.5
        },
        "fleet_utilisation": {
            "value": 20.7,
            "delta": 0.3,
            "label": "Active capacity avg"
        },
        "avg_cost_per_student": {
            "value": 10,
            "delta": -158,
            "currency": "KES",
            "label": "Monthly transport unit cost"
        }
    },
    "message": "Fleet efficiency KPIs retrieved successfully"
}
GET Get Fleet Cost Audit Fleet Reports {{url}}/reports/fleet-efficiency/cost-audit ▸

Paginated per-driver/vehicle cost breakdown: fuel cost, maintenance cost, total cost, trip count, utilization %, and cost per student.

Query Parameters

  • date_range / period (see Get Fleet Efficiency Stats)
  • per_page (integer, optional, default 15, max 50)
  • search (string, optional): Matches driver name or zone/location name.

Notes

  • Only includes drivers with at least one trip in the selected period; sorted by total cost, highest first. Costs are in KES.

Response

Paginated per-driver/vehicle cost breakdown (data) with meta — fuel, maintenance, total, trips, utilization %, cost/student (KES).

Auth
Bearer token
Request Body
{
    "date_range": "2026-04-01,2026-04-30",  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
    "page": 1,  // Page number (starts at 1)
    "per_page": 15  // Page size — how many results per page
}
Sample Response (200 OK)
{
    "data": [
        {
            "driver": {
                "id": "818e3ea7-543b-4739-9567-7a5a3e29e6c7",
                "name": "Test Driver"
            },
            "zone": {
                "id": "55169604-66a9-4eba-b35b-2448ea21ba86",
                "name": "KAP 123"
            },
            "trip_count": 47,
            "utilisation_pct": 14.8,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        },
        {
            "driver": {
                "id": "5ac9decc-e38e-4fc9-9026-354787ff1a18",
                "name": "Collins Muriuki"
            },
            "zone": {
                "id": "410aaf66-5477-4cdf-9c8c-634441757e6a",
                "name": "KCB 551M"
            },
            "trip_count": 29,
            "utilisation_pct": 70.5,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        },
        {
            "driver": {
                "id": "8abb32a6-c7d3-450e-b8fc-09774a1223a7",
                "name": "Mat Tester"
            },
            "zone": {
                "id": "9275c202-0a25-4b8e-ab26-841c63636185",
                "name": "Mat's Bike"
            },
            "trip_count": 19,
            "utilisation_pct": null,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        },
        {
            "driver": {
                "id": "e2fe00f4-898a-48cc-abbe-e47956728478",
                "name": "Kevin Oguta"
            },
            "zone": {
                "id": "025081b6-6e63-4469-a35b-f282815a652c",
                "name": "KDL 365Z"
            },
            "trip_count": 56,
            "utilisation_pct": 10.5,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        },
        {
            "driver": {
                "id": "123e7ea9-7117-4d3c-833c-b43e4021d93c",
                "name": "Kevin Oguta-Tester"
            },
            "zone": {
                "id": "e3e9e95d-c4e1-4b54-9fc2-d54e2b077d64",
                "name": "Mike Car"
            },
            "trip_count": 2,
            "utilisation_pct": 20,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        },
        {
            "driver": {
                "id": "548cfd51-3bcc-48cb-bd3b-6d792065f849",
                "name": "Enoch Test"
            },
            "zone": {
                "id": "9275c202-0a25-4b8e-ab26-841c63636185",
                "name": "KAP School Tour"
            },
            "trip_count": 17,
            "utilisation_pct": null,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        },
        {
            "driver": {
                "id": "7db9e5e4-8d39-4cca-bd61-01a9e8c21d98",
                "name": "Donald ."
            },
            "zone": {
                "id": "feed9143-83d9-41f7-96a0-c098508281a8",
                "name": "Mobile Car"
            },
            "trip_count": 25,
            "utilisation_pct": 1.3,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        },
        {
            "driver": {
                "id": "537800c9-546e-4ce9-b777-ec6e02af2a24",
                "name": "Don Work"
            },
            "zone": {
                "id": "55169604-66a9-4eba-b35b-2448ea21ba86",
                "name": "KAP 123"
            },
            "trip_count": 6,
            "utilisation_pct": 0,
            "fuel_cost": 0,
            "maintenance_cost": 0,
            "total_cost": 0,
            "cost_per_student": 0,
            "currency": "KES"
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8000/api/reports/fleet-efficiency/cost-audit?page=1",
        "last": "http://127.0.0.1:8000/api/reports/fleet-efficiency/cost-audit?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/fleet-efficiency/cost-audit?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "http://127.0.0.1:8000/api/reports/fleet-efficiency/cost-audit",
        "per_page": 15,
        "to": 8,
        "total": 8,
        "period": {
            "from": "2026-04-01",
            "to": "2026-04-30"
        }
    },
    "status": 200,
    "message": "Vehicle cost audit retrieved successfully"
}
GET Average Attendance {{url}}/reports/attendance/average ▸

Average attendance percentage over a period, compared to the prior period of the same length, plus on-time metrics. "Attendance" here means a student tapped/was marked "Checked In" that day — not classroom attendance.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional): Shorthand alternative to date_range.
  • waaszoneuuid (string UUID, optional): Restrict to one zone/location/route.

Notes

  • The URL for this request was corrected from the outdated /reports/average-attendance to the route that actually exists today: /reports/attendance/average.
  • Scoped to your school (Administrative Staff).

Response

Attendance KPIs (data): average attendance %, comparison to the prior period, and on-time metrics.

Auth
Bearer token
Request Body
{
    "date_range": "2026-03-29+00:00:00,2026-04-29+23:59:59",  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
    "waas_zone_uuid": null  // Zone/location UUID (from the WaaS partner system)
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "average_attendance_period_selected": 52.88,
        "average_attendance_last_period": 5.97,
        "attendance_difference": 46.91,
        "percentage_change": 785.76,
        "absences_today": 0,
        "total_students": 50,
        "total_days": 32,
        "total_attendance": 1692,
        "total_attendance_last_period": 191,
        "attendance_by_date": {
            "2026-03-29": 33,
            "2026-03-30": 14,
            "2026-03-31": 3,
            "2026-04-01": 192,
            "2026-04-02": 1,
            "2026-04-03": 60,
            "2026-04-04": 0,
            "2026-04-05": 0,
            "2026-04-06": 1,
            "2026-04-07": 337,
            "2026-04-08": 231,
            "2026-04-09": 29,
            "2026-04-10": 163,
            "2026-04-11": 61,
            "2026-04-12": 14,
            "2026-04-13": 39,
            "2026-04-14": 89,
            "2026-04-15": 157,
            "2026-04-16": 161,
            "2026-04-17": 95,
            "2026-04-18": 0,
            "2026-04-19": 0,
            "2026-04-20": 8,
            "2026-04-21": 0,
            "2026-04-22": 0,
            "2026-04-23": 0,
            "2026-04-24": 0,
            "2026-04-25": 0,
            "2026-04-26": 0,
            "2026-04-27": 0,
            "2026-04-28": 0,
            "2026-04-29": 0
        },
        "attendance_by_date_last_period": {
            "2026-02-25": 0,
            "2026-02-26": 0,
            "2026-02-27": 0,
            "2026-02-28": 1,
            "2026-03-01": 0,
            "2026-03-02": 0,
            "2026-03-03": 13,
            "2026-03-04": 1,
            "2026-03-05": 0,
            "2026-03-06": 0,
            "2026-03-07": 0,
            "2026-03-08": 0,
            "2026-03-09": 14,
            "2026-03-10": 0,
            "2026-03-11": 0,
            "2026-03-12": 6,
            "2026-03-13": 18,
            "2026-03-14": 0,
            "2026-03-15": 0,
            "2026-03-16": 0,
            "2026-03-17": 1,
            "2026-03-18": 5,
            "2026-03-19": 0,
            "2026-03-20": 0,
            "2026-03-21": 0,
            "2026-03-22": 0,
            "2026-03-23": 9,
            "2026-03-24": 39,
            "2026-03-25": 35,
            "2026-03-26": 40,
            "2026-03-27": 3,
            "2026-03-28": 6
        },
        "attendance_rate_by_date": {
            "2026-03-29": 66,
            "2026-03-30": 28,
            "2026-03-31": 6,
            "2026-04-01": 384,
            "2026-04-02": 2,
            "2026-04-03": 120,
            "2026-04-04": 0,
            "2026-04-05": 0,
            "2026-04-06": 2,
            "2026-04-07": 674,
            "2026-04-08": 462,
            "2026-04-09": 58,
            "2026-04-10": 326,
            "2026-04-11": 122,
            "2026-04-12": 28,
            "2026-04-13": 78,
            "2026-04-14": 178,
            "2026-04-15": 314,
            "2026-04-16": 322,
            "2026-04-17": 190,
            "2026-04-18": 0,
            "2026-04-19": 0,
            "2026-04-20": 16,
            "2026-04-21": 0,
            "2026-04-22": 0,
            "2026-04-23": 0,
            "2026-04-24": 0,
            "2026-04-25": 0,
            "2026-04-26": 0,
            "2026-04-27": 0,
            "2026-04-28": 0,
            "2026-04-29": 0
        },
        "attendance_rate_by_date_last_period": {
            "2026-02-25": 0,
            "2026-02-26": 0,
            "2026-02-27": 0,
            "2026-02-28": 2,
            "2026-03-01": 0,
            "2026-03-02": 0,
            "2026-03-03": 26,
            "2026-03-04": 2,
            "2026-03-05": 0,
            "2026-03-06": 0,
            "2026-03-07": 0,
            "2026-03-08": 0,
            "2026-03-09": 28,
            "2026-03-10": 0,
            "2026-03-11": 0,
            "2026-03-12": 12,
            "2026-03-13": 36,
            "2026-03-14": 0,
            "2026-03-15": 0,
            "2026-03-16": 0,
            "2026-03-17": 2,
            "2026-03-18": 10,
            "2026-03-19": 0,
            "2026-03-20": 0,
            "2026-03-21": 0,
            "2026-03-22": 0,
            "2026-03-23": 18,
            "2026-03-24": 78,
            "2026-03-25": 70,
            "2026-03-26": 80,
            "2026-03-27": 6,
            "2026-03-28": 12
        },
        "on_time_average_period_selected": 8.03,
        "on_time_average_last_period": 0.81,
        "on_time_difference": 7.219999999999999,
        "on_time_percentage_change": 891.36,
        "on_time_percentage_period_selected": 15.19,
        "on_time_percentage_last_period": 13.61,
        "on_time_percentage_difference": 1.58,
        "period_start": "2026-03-29",
        "period_end": "2026-04-29",
        "last_period_start": "2026-02-25",
        "last_period_end": "2026-03-28"
    },
    "message": "Average attendance retrieved successfully."
}
GET Attendance Trends {{url}}/reports/attendance/trends ▸

Time-series attendance data over a period — used to render an attendance trend chart.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional): Shorthand alternative to date_range.
  • waaszoneuuid (string UUID, optional): Restrict to one zone/location/route.

Notes

  • Scoped to your school (Administrative Staff).

Response

Time-series attendance data points (data) used to render the trend chart.

Auth
Bearer token
Request Body
{
    "date_range": "2026-04-06+00:00:00,2026-05-06+23:59:59",  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
    "waas_zone_uuid": null  // Zone/location UUID (from the WaaS partner system)
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "attendance_trends_by_date": [
            {
                "date": "2026-03-25",
                "attendance_volume": 35,
                "present": 21,
                "absent": 14,
                "attendance_rate": 60
            },
            {
                "date": "2026-03-26",
                "attendance_volume": 40,
                "present": 39,
                "absent": 1,
                "attendance_rate": 97.5
            },
            {
                "date": "2026-03-27",
                "attendance_volume": 3,
                "present": 3,
                "absent": 0,
                "attendance_rate": 100
            },
            {
                "date": "2026-03-28",
                "attendance_volume": 10,
                "present": 10,
                "absent": 0,
                "attendance_rate": 100
            },
            {
                "date": "2026-03-29",
                "attendance_volume": 33,
                "present": 27,
                "absent": 6,
                "attendance_rate": 81.82
            },
            {
                "date": "2026-03-30",
                "attendance_volume": 14,
                "present": 13,
                "absent": 1,
                "attendance_rate": 92.86
            },
            {
                "date": "2026-03-31",
                "attendance_volume": 3,
                "present": 0,
                "absent": 3,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-01",
                "attendance_volume": 192,
                "present": 192,
                "absent": 0,
                "attendance_rate": 100
            },
            {
                "date": "2026-04-02",
                "attendance_volume": 1,
                "present": 1,
                "absent": 0,
                "attendance_rate": 100
            },
            {
                "date": "2026-04-03",
                "attendance_volume": 60,
                "present": 60,
                "absent": 0,
                "attendance_rate": 100
            },
            {
                "date": "2026-04-04",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-05",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-06",
                "attendance_volume": 1,
                "present": 0,
                "absent": 1,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-07",
                "attendance_volume": 337,
                "present": 309,
                "absent": 28,
                "attendance_rate": 91.69
            },
            {
                "date": "2026-04-08",
                "attendance_volume": 231,
                "present": 227,
                "absent": 4,
                "attendance_rate": 98.27
            },
            {
                "date": "2026-04-09",
                "attendance_volume": 29,
                "present": 20,
                "absent": 9,
                "attendance_rate": 68.97
            },
            {
                "date": "2026-04-10",
                "attendance_volume": 163,
                "present": 131,
                "absent": 32,
                "attendance_rate": 80.37
            },
            {
                "date": "2026-04-11",
                "attendance_volume": 61,
                "present": 41,
                "absent": 20,
                "attendance_rate": 67.21
            },
            {
                "date": "2026-04-12",
                "attendance_volume": 14,
                "present": 14,
                "absent": 0,
                "attendance_rate": 100
            },
            {
                "date": "2026-04-13",
                "attendance_volume": 39,
                "present": 21,
                "absent": 18,
                "attendance_rate": 53.85
            },
            {
                "date": "2026-04-14",
                "attendance_volume": 89,
                "present": 73,
                "absent": 16,
                "attendance_rate": 82.02
            },
            {
                "date": "2026-04-15",
                "attendance_volume": 157,
                "present": 137,
                "absent": 20,
                "attendance_rate": 87.26
            },
            {
                "date": "2026-04-16",
                "attendance_volume": 161,
                "present": 144,
                "absent": 17,
                "attendance_rate": 89.44
            },
            {
                "date": "2026-04-17",
                "attendance_volume": 95,
                "present": 88,
                "absent": 7,
                "attendance_rate": 92.63
            },
            {
                "date": "2026-04-18",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-19",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-20",
                "attendance_volume": 8,
                "present": 8,
                "absent": 0,
                "attendance_rate": 100
            },
            {
                "date": "2026-04-21",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-22",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-23",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-24",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            },
            {
                "date": "2026-04-25",
                "attendance_volume": 0,
                "present": 0,
                "absent": 0,
                "attendance_rate": 0
            }
        ],
        "total_days": 32
    },
    "message": "Attendance trends retrieved successfully."
}
GET Absentee Report {{url}}/reports/attendance/absentee?page=1 ▸

Paginated list of students marked absent (no check-in recorded) within a period.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional): Shorthand alternative to date_range.
  • waaszoneuuid (string UUID, optional): Restrict to one zone/location/route.
  • per_page (integer, optional, default 10, max 20)
  • search (string, optional, capped at 100 characters): Matches student name.

Notes

  • The URL for this request was corrected from the outdated /reports/absentee-report to the route that actually exists today: /reports/attendance/absentee.
  • A same-day total-only variant is available at GET /reports/attendance/absentee/today-total (see Absentee Total (Today)), and a PDF/Excel export at GET /reports/attendance/absentee/export (see Export Absentee Report).

Response

Paginated list of absent students (data) with meta.

Auth
Bearer token
Request Body
{
    "date_range": "2026-02-17+00:00:00,2026-02-20+23:59:59",  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
    "waas_zone_uuid": null  // Zone/location UUID (from the WaaS partner system)
}
Sample Response (200 OK)
{
    "data": [
        {
            "uuid": "7c2ea80b-00f1-4b9f-893c-34297d3b2de3",
            "name": "Zimmer Red",
            "grade": "7th Grade",
            "days_present": 19,
            "days_absent": 16,
            "attendance_percentage": 54.29
        },
        {
            "uuid": "d4a21227-ba49-4a87-8d0a-5a218be6e178",
            "name": "Blue Biggie",
            "grade": "1st Grade",
            "days_present": 0,
            "days_absent": 15,
            "attendance_percentage": 0
        },
        {
            "uuid": "3d226da3-f5c2-4cbb-a068-da3bb222faa4",
            "name": "Zimmer Blue",
            "grade": "5th Grade",
            "days_present": 0,
            "days_absent": 15,
            "attendance_percentage": 0
        },
        {
            "uuid": "6c9c0aca-ec65-4dba-9717-f5a006d54503",
            "name": "Pink Terra",
            "grade": "PP1",
            "days_present": 63,
            "days_absent": 13,
            "attendance_percentage": 82.89
        },
        {
            "uuid": "36c8c306-2018-4841-92d9-71ca1ed3c7c9",
            "name": "Green Child",
            "grade": "3rd Grade",
            "days_present": 57,
            "days_absent": 13,
            "attendance_percentage": 81.43
        },
        {
            "uuid": "ddb0aa8c-b946-4740-8f06-8c4360668fcc",
            "name": "Two Term",
            "grade": "1st Grade",
            "days_present": 13,
            "days_absent": 11,
            "attendance_percentage": 54.17
        },
        {
            "uuid": "37d8f22c-98bf-47fc-916e-15c96e20de36",
            "name": "Kipsss Kidddds",
            "grade": "12th Grade",
            "days_present": 13,
            "days_absent": 11,
            "attendance_percentage": 54.17
        },
        {
            "uuid": "18435a9c-5822-4f31-9a56-aca28e2a038d",
            "name": "Middle PM",
            "grade": "5th Grade",
            "days_present": 13,
            "days_absent": 10,
            "attendance_percentage": 56.52
        },
        {
            "uuid": "09e85c35-5998-4362-beed-297c92a4e851",
            "name": "Disi New",
            "grade": "PP1",
            "days_present": 14,
            "days_absent": 10,
            "attendance_percentage": 58.33
        },
        {
            "uuid": "0b1475e9-f811-4683-8a90-a94468dc7ef1",
            "name": "Junior Pm",
            "grade": "8th Grade",
            "days_present": 12,
            "days_absent": 10,
            "attendance_percentage": 54.55
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8000/api/reports/absentee-report?page=1",
        "last": "http://127.0.0.1:8000/api/reports/absentee-report?page=4",
        "prev": null,
        "next": "http://127.0.0.1:8000/api/reports/absentee-report?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 4,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/absentee-report?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/absentee-report?page=2",
                "label": "2",
                "page": 2,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/absentee-report?page=3",
                "label": "3",
                "page": 3,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/absentee-report?page=4",
                "label": "4",
                "page": 4,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/absentee-report?page=2",
                "label": "Next »",
                "page": 2,
                "active": false
            }
        ],
        "path": "http://127.0.0.1:8000/api/reports/absentee-report",
        "per_page": 10,
        "to": 10,
        "total": 35
    },
    "status": 200,
    "message": "Absentee report retrieved successfully."
}
GET Late Arrivals {{url}}/reports/attendance/late ▸

Paginated list of students who checked in later than expected within a period.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional): Shorthand alternative to date_range.
  • waaszoneuuid (string UUID, optional): Restrict to one zone/location/route.
  • per_page (integer, optional, default 10, max 20)
  • search (string, optional)

Notes

  • The URL for this request was corrected from the outdated /reports/late-arrivals to the route that actually exists today: /reports/attendance/late.
  • A PDF/Excel export variant is available at GET /reports/attendance/late/export (see Export Late Arrivals).

Response

Paginated list of late students (data) with meta — name, average arrival and late_days.

Auth
Bearer token
Request Body
{
    "date_range": "2023-02-17+00:00:00,2026-04-20+23:59:59",  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
    "waas_zone_uuid": null  // Zone/location UUID (from the WaaS partner system)
}
Sample Response (200 OK)
{
    "data": [
        {
            "uuid": "6c9c0aca-ec65-4dba-9717-f5a006d54503",
            "name": "Pink Terra",
            "mode": "Manual",
            "avg_arrival": 66.67,
            "late_days": 12
        },
        {
            "uuid": "7ecc2ed5-e771-4a4a-b841-a813b39d36e4",
            "name": "Grace Sang",
            "mode": null,
            "avg_arrival": 100,
            "late_days": 10
        },
        {
            "uuid": "36c8c306-2018-4841-92d9-71ca1ed3c7c9",
            "name": "Green Child",
            "mode": "Manual",
            "avg_arrival": 58.82,
            "late_days": 10
        },
        {
            "uuid": "7c2ea80b-00f1-4b9f-893c-34297d3b2de3",
            "name": "Zimmer Red",
            "mode": null,
            "avg_arrival": 83.33,
            "late_days": 10
        },
        {
            "uuid": "e8c02700-5e8f-4a4b-8356-8f67a769ec22",
            "name": "Cynthia Okoth",
            "mode": null,
            "avg_arrival": 88.89,
            "late_days": 8
        },
        {
            "uuid": "09e85c35-5998-4362-beed-297c92a4e851",
            "name": "Disi New",
            "mode": "Manual",
            "avg_arrival": 66.67,
            "late_days": 8
        },
        {
            "uuid": "4ff672b0-0ff2-4f06-8f5c-9e60bc9783b2",
            "name": "David Wairimu",
            "mode": null,
            "avg_arrival": 70,
            "late_days": 7
        },
        {
            "uuid": "c90b0f26-6671-49f7-9e12-d9da8b70677d",
            "name": "Mercy Odhiambo",
            "mode": null,
            "avg_arrival": 70,
            "late_days": 7
        },
        {
            "uuid": "6150b949-b087-49b0-9891-1e6d7de03afa",
            "name": "Esther Ouma",
            "mode": null,
            "avg_arrival": 77.78,
            "late_days": 7
        },
        {
            "uuid": "cf18377d-c3ac-4424-8535-c7fbf72ac5a9",
            "name": "Ann Okoth",
            "mode": null,
            "avg_arrival": 77.78,
            "late_days": 7
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8000/api/reports/late-arrivals?page=1",
        "last": "http://127.0.0.1:8000/api/reports/late-arrivals?page=4",
        "prev": null,
        "next": "http://127.0.0.1:8000/api/reports/late-arrivals?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 4,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/late-arrivals?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/late-arrivals?page=2",
                "label": "2",
                "page": 2,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/late-arrivals?page=3",
                "label": "3",
                "page": 3,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/late-arrivals?page=4",
                "label": "4",
                "page": 4,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/reports/late-arrivals?page=2",
                "label": "Next »",
                "page": 2,
                "active": false
            }
        ],
        "path": "http://127.0.0.1:8000/api/reports/late-arrivals",
        "per_page": 10,
        "to": 10,
        "total": 31
    },
    "status": 200,
    "message": "Late arrivals report retrieved successfully."
}
GET Zone/Location With Highest On-Time Rate {{url}}/reports/attendance/zone-highest-rate ▸

Identify which zone/location/route has the best on-time attendance rate over a period — useful for highlighting a well-run route or spotting outliers.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional): Shorthand alternative to date_range.
  • waaszoneuuid (string UUID, optional): Restrict to one zone/location/route.

Response

The best-performing zone/route (data) with its on-time rate.

Auth
Bearer token
Request Body
{
    "date_range": "2026-02-01+00:00:00,2026-04-20+23:59:59",  // Date filter — "YYYY-MM-DD,YYYY-MM-DD" (start,end)
    "waas_zone_uuid": null  // Zone/location UUID (from the WaaS partner system)
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "highest": {
            "zone_type": "Mobile",
            "count": 283
        },
        "zones": [
            {
                "zone_type": "Mobile",
                "count": 283
            }
        ]
    },
    "message": "Zone highest on-time rate retrieved successfully."
}
GET Absentee Total (Today) {{url}}/reports/attendance/absentee/today-total ▸

Lightweight companion to Absentee Report — returns just the count of students with no check-in today, for a dashboard badge/counter (no per-student list).

Query Parameters

  • waaszoneuuid (string UUID, optional): Restrict the count to one zone/location/route. Validated against the registry; an invalid id returns an error.

Response

{ "total": <integer> } — today's absentee count.

Notes

  • Always scoped to today (server date) and to your school (Administrative Staff; staff/others resolve to their supervisor's school).
  • Requires a bearer token (auth:api).
Auth
Bearer token
GET Export Absentee Report {{url}}/reports/attendance/absentee/export ▸

Generate a downloadable Absentee Report (PDF or Excel) for a period and email it to the requester (and optional CC recipients). The file is built asynchronously via a background job — the endpoint returns immediately once the export is queued.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional): Shorthand alternative to date_range.
  • waaszoneuuid (string UUID, optional): Restrict to one zone/location/route.
  • format (string): pdf or excel (also accepts export_type).
  • cc (string/array, optional): Extra recipients (also accepts receivers).

Response

"Data export initiated successfully" — the report is emailed when the job finishes; it is not returned in the response body.

Notes

  • Same date-range validation as the Absentee Report (range cannot exceed 365 days).
  • Scoped to your school; the institution name is stamped on the export.
  • Requires a bearer token (auth:api).
Auth
Bearer token
GET Export Late Arrivals {{url}}/reports/attendance/late/export ▸

Generate a downloadable Late Arrivals Report (PDF or Excel) for a period and email it to the requester (and optional CC recipients). Built asynchronously via a background job; the endpoint returns as soon as the export is queued.

Query Parameters

  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD".
  • period (string, optional): Shorthand alternative to date_range.
  • waaszoneuuid (string UUID, optional): Restrict to one zone/location/route.
  • format (string): pdf or excel (also accepts export_type).
  • cc (string/array, optional): Extra recipients (also accepts receivers).

Response

"Data export initiated successfully" — the report is emailed when the job finishes.

Notes

  • The export counterpart to Late Arrivals (GET /reports/attendance/late).
  • Scoped to your school; requires a bearer token (auth:api).
Auth
Bearer token
GET Export Parents Directory {{url}}/reports/parents/export ▸

Generate a downloadable Parents Directory (PDF or Excel) of the school's parents and email it to the requester (and optional CC recipients). Built asynchronously via a background job.

Query Parameters

  • format (string): pdf or excel (also accepts export_type).
  • cc (string/array, optional): Extra recipients (also accepts receivers).

Response

"Data export initiated successfully" — the directory is emailed when the job finishes.

Notes

  • Scoped to your school (Administrative Staff; others resolve to their supervisor's school); the institution name is stamped on the export.
  • Requires a bearer token (auth:api).
Auth
Bearer token
Used On
Manage Parents
GET Admin — Daily Taps {{url}}/reports/admin/daily-taps ▸

Org-wide (not school-scoped) admin-dashboard metric: how many distinct active students were marked PRESENT in a window, versus the total active student base — i.e. daily platform "tap" adoption.

Query Parameters

  • period_start (date, optional, default today): Start of the window (start of day).
  • period_end (date, optional, default today): End of the window (end of day).

Response

uniquestudents, totalstudents (all active students), percentage (unique / total × 100), and the resolved periodstart / periodend.

Notes

  • Counts distinct students with a PRESENT roll-call in the window.
  • This is a system-admin endpoint — it aggregates across all schools, not just the caller's.
  • Requires a bearer token (auth:api).
Auth
Bearer token
GET Admin — Overview Stats {{url}}/reports/admin/overview-stats ▸

Org-wide week-over-week growth for the four admin-dashboard cards: parents, schools, kids, and buses (bus minders). Compares records created this week (Monday→now) against the previous full week.

Response

For each of parents, schools, kids, buses:

  • this_week — count created this week.
  • last_week — count created the prior week.
  • delta_pct — percentage change vs last week, or null when there's no prior-week baseline (UI then shows the raw "+N this week").

Also returns period.thisweekstart / period.lastweekstart.

Notes

  • "schools" = Administrative Staff users; "buses" = Staff with stafftype = BUSMINDER; "kids" = all students.
  • System-admin endpoint — aggregates across all schools.
  • Requires a bearer token (auth:api).
Auth
Bearer token
GET Admin — List Report Schedule Settings {{url}}/reports/admin/report-schedule-settings ▸

List the automated report delivery schedules, one entry per frequency (Daily, Weekly, Monthly). Returns the configured settings if present, or defaults for any frequency not yet configured.

Response

An array of settings, each with frequency, sendat, dayofweek, dayofmonth, weekdaysonly, timezone, is_enabled, and a human-readable schedule summary.

Notes

  • Pairs with Update Report Schedule Setting to enable/disable and tune each schedule.
  • System-admin endpoint. Requires a bearer token (auth:api).
Auth
Bearer token
PUT Admin — Update Report Schedule Setting {{url}}/reports/admin/report-schedule-settings/Daily ▸

Create or update the automated report schedule for a given frequency (Daily, Weekly, or Monthly). Upserts the setting for that frequency.

Path Parameters

  • frequency (string, required): One of Daily, Weekly, Monthly. An invalid value returns a validation error.

Request Body

  • send_at (string, required): Delivery time, HH:mm (send hour must be within the allowed window, 05:00–20:00).
  • timezone (string, required): Must be one of the allowed timezones.
  • dayofweek (integer, optional): 1–7 (Mon–Sun) — used for Weekly.
  • dayofmonth (integer, optional): 1–28 — used for Monthly.
  • weekdays_only (boolean, optional): For Daily, restrict sends to weekdays.
  • is_enabled (boolean, optional): Turn this schedule on/off.

Response

The upserted schedule setting.

Notes

  • System-admin endpoint. Requires a bearer token (auth:api).
Auth
Bearer token
Request Body
{
    "send_at": "07:00",  // Time of day to send (HH:mm, 24-hour)
    "timezone": "Africa/Nairobi",  // Timezone, e.g. Africa/Nairobi
    "weekdays_only": true,  // Only send on weekdays (Mon–Fri)
    "is_enabled": true  // Turn this schedule on/off
}