TerraGo API

Students

Students (children) transported by the platform. Covers student CRUD, guardian links, home addresses, Band/Bag Tags band assignment, the pickup-authorization OTP flow (generate / validate / confirm) used at handover, route-ordering rosters, trip check-points (pickup/drop-off), and assignment of a student to trip planner(s).

24 endpoint(s)
GET List {{url}}/dependants ▸

Retrieves a paginated list of students filtered by optional criteria such as tags, parent ID, or phone number. This endpoint is useful for applications that need to display or manage students associated with a parent entity (such as a user or account).

Parameters

  • tags (array[string], optional): List of tag UUIDs to filter students.
  • parent_id (string, optional): UUID of the parent entity to filter students.
  • phone_number (string, optional): Phone number to filter students.
  • per_page (integer, optional): Number of results per page. Default is 10.
  • page (integer, optional): Page number to retrieve. Default is 1.

Notes

  • All filter parameters are optional; omitting them returns all students.
  • Ensure the token environment variable is set with a valid bearer token.
  • The endpoint may return an empty array if no students match the filters.
Auth
Bearer token
Used On
Route ProfileAll Students
Request Body
{
    "tags": ["d4b18b8f-eaa6-44e1-8655-d75f146c0933"], // filter by tag
    // "parent_id": "cf7a3821-e6be-490f-85b9-6f7ca3585aad", // filter by parent id
    // "phone_number": "+254733556677",  // filter by phone number
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "184c32e2-878d-4e89-99c3-91dda70c03e9",
            "first_name": "Simon",
            "middle_name": "Kimani",
            "last_name": "Chege",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2010-11-06 00:00:00",
            "gender": "Male",
            "third_party_id": "a2fce066-519c-4cba-968d-18aa70446411",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "cf7a3821-e6be-490f-85b9-6f7ca3585aad",
                "name": "Kevin Kariuki",
                "email": "kevin.kariuki@example.com",
                "phone": "+254733556677"
            },
            "guardians": [
                {
                    "uuid": "d651190e-5e68-43e0-82db-9c53426311ab",
                    "name": "Peter Chege"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-05 15:51:29",
            "addresses": [
                {
                    "uuid": "93d41cd9-1b01-4bb3-95ce-56175ce7f493",
                    "is_primary": 1,
                    "latitude": "-1.2921",
                    "longitude": "36.8219"
                }
            ],
            "tags": [
                {
                    "id": "d4b18b8f-eaa6-44e1-8655-d75f146c0933",
                    "name": "PM School Tag",
                    "description": "PM School Tag",
                    "entity": "universal",
                    "color_code": "#EA0D8D"
                }
            ]
        },
        {
            "id": "0b1475e9-f811-4683-8a90-a94468dc7ef1",
            "first_name": "Junior",
            "middle_name": null,
            "last_name": "Pm",
            "phone": "",
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2005-01-05 00:00:00",
            "gender": "Female",
            "third_party_id": "2b8effd8-0782-4e66-b93f-d0ba8c4464c9",
            "is_active": 1,
            "metadata": {
                "grade": "8th Grade"
            },
            "parent": {
                "uuid": "d23b811d-368c-44fd-a031-6663bed28fc0",
                "name": "Pm Parent",
                "email": "Parent@gmail.com",
                "phone": "+254791472893"
            },
            "guardians": [
                {
                    "uuid": "41e5db5b-2ab2-4d8a-a8e2-6fe3fdaca078",
                    "name": "Nanny Guardian"
                },
                {
                    "uuid": "4d95c454-67aa-47ce-80c3-973f0d3750cb",
                    "name": "Maggy Grants"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2026-01-05 14:26:56",
            "addresses": [],
            "tags": [
                {
                    "id": "d4b18b8f-eaa6-44e1-8655-d75f146c0933",
                    "name": "PM School Tag",
                    "description": "PM School Tag",
                    "entity": "universal",
                    "color_code": "#EA0D8D"
                },
                {
                    "id": "0655ca5b-1c6b-437d-b38a-7f4596fb038f",
                    "name": "Kiota School Rongai Route",
                    "description": "Kiota School Rongai Route for students",
                    "entity": "dependant",
                    "color_code": null
                }
            ]
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8001/api/dependants?page=1",
        "last": "http://127.0.0.1:8001/api/dependants?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:8001/api/dependants?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "http://127.0.0.1:8001/api/dependants",
        "per_page": 10,
        "to": 2,
        "total": 2
    },
    "status": 200,
    "message": "Dependants Retrieved Successfully"
}
POST Add {{url}}/dependants/add ▸

This endpoint creates a new student record associated with a parent user.

Sample Fields

  • first_name (string): Student's first name.
  • middle_name (string): Student's middle name.
  • last_name (string): Student's last name.
  • dob (string): Date of birth (format: DD-MM-YYYY).
  • gender (string): Gender of the student. Allowed values: MALE, FEMALE, OTHER, N/A.
  • parent_id (string): Unique identifier of the parent user.

Response

The created student (data) — id (uuid), names, grade, parent, guardians, addresses.

Auth
Bearer token
Used On
Add Student Modal
Request Body
{
    "first_name" : "Simon",
    "middle_name": "Kimani",
    "last_name" : "Chege",
    "dob":"06-11-2010",
    "gender": "MALE", //only use: MALE, FEMALE, OTHER, N/A
    "parent_id" : "cf7a3821-e6be-490f-85b9-6f7ca3585aad",
    "metadata" : {
        "grade" : "Grade 6" //only use: PP1, PP2, PLAYGROUP, GRADE_1 , GRADE_2, GRADE_3, GRADE_4, GRADE_5, GRADE_6, GRADE_7, GRADE_8, GRADE_9, GRADE_10, GRADE_11, GRADE_12, COLLEGE, N/A,
    },
    "tags" : ["cf7a3821-e6be-490f-85b9-6f7ca3585aad", "cf7a3821-e6be-490f-85b9-6f7ca3585aad"],
    "search_term": "Malaika School Thika Road" //optional for the search term used by the parent to find the dependants institution
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "184c32e2-878d-4e89-99c3-91dda70c03e9",
        "first_name": "Simon",
        "middle_name": "Kimani",
        "last_name": "Chege",
        "phone": null,
        "email": null,
        "identification_document": null,
        "identification_number": null,
        "dob": "2010-11-06 00:00:00",
        "gender": "Male",
        "third_party_id": "a2fce066-519c-4cba-968d-18aa70446411",
        "is_active": true,
        "metadata": {
            "grade": null
        },
        "image": null,
        "notes": null,
        "created_at": "2025-12-05 12:51:29"
    },
    "message": "Dependant Created Successfully"
}
PUT Update {{url}}/dependants/update/30a250fe-0cbe-4afb-bb48-606e5d8f887f ▸

This endpoint updates the details of an existing student identified by their unique ID in the URL path.

Sample Body Fields:

  • first_name (string, required): Student's first name. Example: "Lincoln"
  • middle_name (string, optional): Student's middle name. Example: "Hungi"
  • last_name (string, required): Student's last name. Example: "Chege"
  • dob (string, required): Date of birth in DD-MM-YYYY format. Example: "06-11-2010"
  • gender (string, required): Gender of the student. Allowed values: MALE, FEMALE, OTHER, N/A
  • parent_id (string, required): UUID of the parent.
  • metadata (object, optional): Additional information. Example: { "grade": "Grade 6" }

Response

The updated student (data).

Auth
Bearer token
Request Body
{
    "first_name" : "Lincoln",
    "middle_name": "Hungi",
    "last_name" : "Chege",
    "dob":"06-11-2010",
    "gender": "MALE", //only use: MALE, FEMALE, OTHER, N/A
    "parent_id" : "b3b62c15-1409-4713-81b2-d4f6744039e6",
    "metadata" : {
        "grade" : "Grade 6" //only use: PP1, PP2, PLAYGROUP, GRADE_1 , GRADE_2, GRADE_3, GRADE_4, GRADE_5, GRADE_6, GRADE_7, GRADE_8, GRADE_9, GRADE_10, GRADE_11, GRADE_12, COLLEGE, N/A,
    },
    "tags" : ["cf7a3821-e6be-490f-85b9-6f7ca3585aad", "cf7a3821-e6be-490f-85b9-6f7ca3585aad"],
    "search_term": "Malaika School Thika Road" //optional for the search term used by the parent to find the dependants institution
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f",
        "first_name": "Lincoln",
        "middle_name": "Hungi",
        "last_name": "Chege",
        "phone": null,
        "email": null,
        "identification_document": null,
        "identification_number": null,
        "dob": "2010-11-06 00:00:00",
        "gender": "Male",
        "third_party_id": "6e09a88f-de47-455b-a1bd-dc83a6e8efc6",
        "is_active": true,
        "metadata": {
            "grade": "Grade 6"
        },
        "image": null,
        "notes": null,
        "created_at": "2025-11-21 11:07:08"
    },
    "message": "Dependant Updated Successfully"
}
GET Show {{url}}/dependants/184c32e2-878d-4e89-99c3-91dda70c03e9 ▸

Retrieve a single student (child) by UUID with their full context, enriched from the registry.

Path Parameters

  • id (string UUID, required): The student's UUID.

Response includes

  • Local relationships: parent, guardians, and addresses.
  • the registry enrichment: the student's live the registry record is fetched and merged in, providing route/zone/location tags and assigned Band/Bag Tags devices (mapped onto the response).

Notes

  • Returns 404 if no student matches the UUID.
  • If the registry is unreachable the local data is still returned; the the registry-derived tags/IOTs are simply omitted.
  • Requires a bearer token (auth:api).
Auth
Bearer token
Used On
Student Profile
Sample Response (200 OK)
{
    "data": {
        "id": "184c32e2-878d-4e89-99c3-91dda70c03e9",
        "first_name": "Simon",
        "middle_name": "Kimani",
        "last_name": "Chege",
        "phone": null,
        "email": null,
        "identification_document": null,
        "identification_number": null,
        "dob": "2010-11-06 00:00:00",
        "gender": "Male",
        "third_party_id": "a2fce066-519c-4cba-968d-18aa70446411",
        "is_active": 1,
        "metadata": {
            "grade": null
        },
        "parent": {
            "uuid": "cf7a3821-e6be-490f-85b9-6f7ca3585aad",
            "name": "Kevin Kariuki",
            "email": "kevin.kariuki@example.com",
            "phone": "+254733556677"
        },
        "guardians": [
            {
                "uuid": "d651190e-5e68-43e0-82db-9c53426311ab",
                "name": "Peter Chege"
            }
        ],
        "image": null,
        "notes": null,
        "created_at": "2025-12-05 15:51:29",
        "addresses": [
            {
                "uuid": "93d41cd9-1b01-4bb3-95ce-56175ce7f493",
                "is_primary": 1,
                "latitude": "-1.2921",
                "longitude": "36.8219"
            },
            {
                "uuid": "da879dcb-b062-462e-b935-5c1b879e3c0d",
                "is_primary": 1,
                "latitude": "-1.2921",
                "longitude": "36.8219"
            }
        ]
    },
    "status": 200,
    "message": "Dependant Retrieved Successfully"
}
POST SyncGuardians {{url}}/dependants/sync-guardians/184c32e2-878d-4e89-99c3-91dda70c03e9 ▸

Synchronizes the list of guardians for a specific student. This endpoint updates the guardians associated with a student by replacing the current list with the provided array of guardian UUIDs.

Response

The student's resulting linked guardians (data, array).

Auth
Bearer token
Request Body
{
    "guardians": ["d651190e-5e68-43e0-82db-9c53426311ab"]  // List of guardian UUIDs
}
Sample Response (200 OK)
{
    "status": 200,
    "data": [
        {
            "id": "d651190e-5e68-43e0-82db-9c53426311ab",
            "first_name": "Peter",
            "middle_name": "Kimani",
            "last_name": "Chege",
            "phone": "+254722626879",
            "email": null,
            "identification_document": "national_id",
            "identification_number": "36898912",
            "dob": "2000-11-06 00:00:00",
            "gender": "Male",
            "third_party_id": null,
            "is_active": true,
            "metadata": null,
            "image": null,
            "notes": null,
            "created_at": "2025-12-05 13:00:23"
        }
    ],
    "message": "guardians synced Successfully"
}
POST GenerateAuthOTP {{url}}/dependants/generate-authorization-otp/0b1475e9-f811-4683-8a90-a94468dc7ef1 ▸

Generates an authorization OTP (One-Time Password) for a student using the specified guardian ID.

Required Parameters:

  • Path: dependant_id (UUID) – The unique identifier of the student for whom the OTP is being generated.
  • Body (JSON): guardian_id (array of UUIDs) – One or more guardian IDs associated with the student.

Response

Confirmation the OTP was generated (data). The code is delivered to the authorized person — it is not returned in the response.

Auth
Bearer token
Request Body
{
    "guardian_id": "41e5db5b-2ab2-4d8a-a8e2-6fe3fdaca078",
    // "parent_id": "d651190e-5e68-43e0-82db-9c53426311ab",
    "valid_minutes" : 120 //Optional: default and max is 120mins, 
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "otp": "1492",
        "expires_at": "2025-12-17 15:39:01"
    },
    "message": "Authorization OTP Generated Successfully"
}
POST validateAuthOTP {{url}}/dependants/validate-authorization-otp ▸

Validate an authorization OTP presented when someone (a parent or guardian) attempts to collect a child — e.g. at pickup/dropoff verification. Confirms the person is authorized for that specific child before handover.

Request Body

  • authorization_otp (string, required): The OTP code being presented.
  • grade (string, required): The child's grade; must be one of the allowed Student::GRADE keys.
  • tags (array, required): The route/zone/location tags in the current context. The OTP matches only if all of the OTP's tags are contained in this list.

Response

  • Valid → returns the student (id, names, dob, gender, metadata) and the authorized_person (id, type = Parent/Guardian, names, phone, gender) with message "OTP valid. Person is authorized."
  • Invalid / expired → records a Declined entry in the authorization OTP history and returns a warning "Invalid or expired OTP, Person not authorized."

Notes

  • An OTP only matches while unexpired, for the correct grade, and with matching tags.
  • This is the validation/lookup step; Confirm Authorization OTP is the follow-up that records the final Verified/Declined decision.
  • Requires a bearer token (auth:api).
Auth
Bearer token
Used On
Pickup Verification
Request Body
{
    "authorization_otp": "2072",
    "grade": "GRADE_8", //only use: PP1, PP2, PLAYGROUP, GRADE_1 , GRADE_2, GRADE_3, GRADE_4, GRADE_5, GRADE_6, GRADE_7, GRADE_8, GRADE_9, GRADE_10, GRADE_11, GRADE_12, COLLEGE, N/A,
    "tags": ["d4b18b8f-eaa6-44e1-8655-d75f146c0933","8a6b4d09-51ba-406b-8f69-db72406d6b7f","47f17aff-fb5a-4469-9fd0-6cd379b70f7a","762aa069-510e-4732-8099-95893d5d51c9","e3ee3b73-edfc-4bba-ad1e-cf237819e774","4e703369-78d2-4646-a937-9fc8abf78be8","b8c95dde-4268-46b5-b318-3a1bb4e008ce"]
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "dependant": {
            "id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f",
            "first_name": "Lincoln",
            "middle_name": "Hungi",
            "last_name": "Chege",
            "dob": "2010-11-06",
            "gender": "Male",
            "metadata": {
                "grade": "6th Grade"
            }
        },
        "authorized_person": {
            "id": "ba20fb10-c2c1-4951-9903-53c6fdbeabef",
            "first_name": "Peter",
            "middle_name": "Kimani",
            "last_name": "Chege",
            "phone": "+254722626879",
            "gender": "Male",
            "metadata": null
        }
    },
    "message": "OTP confirmed. Person is authorized."
}
POST Confirm Authorization OTP {{url}}/dependants/confirm-authorization-otp ▸

Final step of the guardian pickup authorization flow. Records whether the person presenting the OTP (validated via validateAuthOTP) is confirmed to pick up the child, creating a permanent audit record and invalidating the OTP so it cannot be reused.

Request Body

  • status (string, required): Verified (person is authorized to take the child) or Declined (rejected).
  • authorization_otp (string, required): The 4-digit OTP that was validated.
  • dependant_id (string UUID, required): The child's UUID.
  • verifiable_id (string UUID, required): UUID of the parent or guardian the OTP was issued to.
  • verifiable_type (string, required): Parent or Guardian.

Response

A confirmation message: "OTP confirmed. Person is authorized." or "OTP declined. Person not authorized."

Notes

  • This call expires the OTP (one-time use) regardless of outcome, and writes an entry to the OTP history audit trail (see OTP History).
  • Fails if the OTP has already expired or doesn't match the given student/verifiable pair.
Auth
Bearer token
Used On
Pickup Verification
Request Body
{
    "status": "Verified", //Verified,Declined
    "authorization_otp": "8729",
    "dependant_id": "c75f2355-2f88-40b2-916b-999744d1d1f5",
    "verifiable_id": "95db0ec4-83ab-4a7a-aff4-383e738e8d34",
    "verifiable_type" : "Parent" //Parent,Guardian
}
Sample Response (422 Unprocessable Content)
{
    "status": 422,
    "data": [],
    "message": "Invalid or expired OTP, Person not authorized."
}
GET OTP History {{url}}/otp-history ▸

Retrieve a paginated audit trail of every guardian-pickup OTP attempt (both verified and declined), across all students. Use this to investigate a specific pickup or spot suspicious activity.

Query Parameters

  • status (string, optional): Verified or Declined.
  • dependant_id (string UUID, optional): Filter to a specific child.
  • datefrom / dateto (date, optional): Restrict to a date range.
  • search (string, optional): Free-text match against the student/authorized-person name or event details.
  • per_page (integer, optional, default 10, max 20)

Response

Paginated list of OTP history entries, newest first.

Auth
Bearer token
Used On
Verification History
Sample Response (200 OK)
{
    "data": [
        {
            "time": "09:57 AM",
            "date": "12/12/2025",
            "status": "Verified",
            "student": {
                "id": "61072d3d-92a6-4712-a9b3-9d74d2d59346",
                "first_name": "Simon",
                "last_name": "Chege"
            },
            "details": "Guardian: Peter Chege"
        },
        {
            "time": "09:57 AM",
            "date": "12/12/2025",
            "status": "Declined",
            "student": null,
            "details": "Invalid or expired OTP"
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8001/api/otp-history?page=1",
        "last": "http://127.0.0.1:8001/api/otp-history?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:8001/api/otp-history?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "http://127.0.0.1:8001/api/otp-history",
        "per_page": 15,
        "to": 2,
        "total": 2
    }
}
GET OTP Summary {{url}}/otp-history/summary ▸

Retrieve aggregate statistics for the guardian-pickup OTP flow — useful for a security/overview dashboard.

Response

{
  "total_attempts": 150,
  "verified_pickups": 145,
  "success_rate": "96.67%",
  "declined_attempts": 5,
  "security_flags": 2
}

Notes

  • security_flags counts declined OTP attempts in the last 24 hours, which may indicate an attempted unauthorized pickup.
Auth
Bearer token
Used On
Verification History
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "total_attempts": 2,
        "verified_pickups": 1,
        "success_rate": "50%",
        "declined_attempts": 1,
        "security_flags": 0
    },
    "message": "OTP summary retrieved successfully."
}
POST Live Tracking Link {{url}}/dependants/live-tracking-link ▸

Generates a weblink for tracking students live trip location.

Required Parameters:

  • Path: dependant_id (UUID) – The unique identifier of the student for whom the parent wishes to track

Response

A short-lived live-tracking URL (data) the parent can open to watch the child's trip on a map.

Auth
Bearer token
Request Body
{
    "dependant_id": "30a250fe-0cbe-4afb-bb48-606e5d8f887f"  // Student UUID
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "live_tracking_link": "https://terragoui.terrasofthq.com/live-trip/772affd7-5886-4ae7-8724-c5bf64d2853a"
    },
    "message": "success"
}
POST Assign Band/Bag Tags {{url}}/dependants/assign-iot/184c32e2-878d-4e89-99c3-91dda70c03e9 ▸

Assign a wearable Band/Bag Tags tracking band/tag to a student (child), so the child's tap-in/tap-out events can be captured by scanners. Pulls device info from both TerraGo's local Band/Bag Tags stock and TerraGo's zone/location and tag registry.

Path Parameters

  • id (string UUID, required): The student's UUID.

Request Body

  • iotserialnumber (string, required): Serial number printed on/embedded in the device.
  • iot_type (string UUID, required): Band/Bag Tags device type UUID (see GET /utility/band/bag tag-types).
  • administrative_id (string UUID, optional): The school (Administrative Staff) the device belongs to. Defaults to the authenticated user's school/supervisor if omitted.

Response

The updated student record with its assigned Band/Bag Tags device(s).

Notes

  • If the device already exists in local stock, it must be AVAILABLE and belong to the same school — otherwise you'll get a 400 (already assigned elsewhere) or 403.
  • If not found anywhere (neither local stock nor the registry), returns 404.
  • Only System Admins can assign devices across schools; other roles are restricted to their own school's stock.
Auth
Bearer token
Used On
All StudentsStudent Profile
Request Body
{
    "iot_serial_number": "b923a161-df11-4479-ae88-baf42443566",  // Serial number of the band/bag tag device
    "iot_type": "155c2ef7-d959-4e4b-82a6-a8035aed5a64"  // Band/bag tag device-type UUID
}
Sample Response (200 OK)
{
    "data": {
        "id": "184c32e2-878d-4e89-99c3-91dda70c03e9",
        "first_name": "Simon",
        "middle_name": "Kimani",
        "last_name": "Chege",
        "phone": null,
        "email": null,
        "identification_document": null,
        "identification_number": null,
        "dob": "2010-11-06 00:00:00",
        "gender": "Male",
        "third_party_id": "a2fce066-519c-4cba-968d-18aa70446411",
        "is_active": true,
        "metadata": {
            "grade": null
        },
        "parent": {
            "uuid": "cf7a3821-e6be-490f-85b9-6f7ca3585aad",
            "name": "Kevin Kariuki",
            "email": "kevin.kariuki@example.com",
            "phone": "+254733556677"
        },
        "guardians": [
            {
                "uuid": "d651190e-5e68-43e0-82db-9c53426311ab",
                "name": "Peter Chege"
            }
        ],
        "image": null,
        "notes": null,
        "created_at": "2025-12-05 12:51:29",
        "iots": {
            "id": "44de4102-10cb-4df0-838d-ba5d7189d715",
            "assignee": {
                "id": "a2fce066-519c-4cba-968d-18aa70446411",
                "name": "Simon Chege",
                "third_party_id": "184c32e2-878d-4e89-99c3-91dda70c03e9"
            },
            "serial_number": "b923a161-df11-4479-ae88-baf42443566",
            "account_id": "a2fce066-519c-4cba-968d-18aa70446411",
            "code": "IOT-B20C4A9A46I",
            "expires_at": "Mon, Jan 8, 2035 9:37 AM",
            "validity": "8 years from now",
            "expired": false,
            "status": "Active",
            "user_type": "Dependant",
            "wallet_id": "a2fce066-519c-4cba-968d-18aa70446411",
            "iot_type": {
                "id": "155c2ef7-d959-4e4b-82a6-a8035aed5a64",
                "name": "nfc wristband"
            },
            "tags": [],
            "created_at": "Thu, Jan 8, 2026 12:37 PM"
        }
    },
    "status": 200,
    "message": "Dependant IOT Assigned Successfully"
}
POST Add Student Address {{url}}/dependants/add-address/184c32e2-878d-4e89-99c3-91dda70c03e9 ▸

Attach a saved location (typically home or school) to a student's profile, used for geofencing and the "home address auto-detection" feature.

Path Parameters

  • id (string UUID, required): The student's UUID.

Request Body

  • latitude (number, required, range -90 to 90)
  • longitude (number, required, range -180 to 180)
  • is_primary (boolean, required): Marks this as the student's primary address.

Notes

  • Setting isprimary: true automatically un-sets isprimary on any other address already saved for this student — a student can only have one primary address at a time.

Response

The created address (data).

Auth
Bearer token
Request Body
{
    "latitude": -1.2921,
    "longitude": 36.8219,
    "is_primary": true //use only: true, false
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "uuid": "da879dcb-b062-462e-b935-5c1b879e3c0d",
        "is_primary": true,
        "latitude": -1.2921,
        "longitude": 36.8219
    },
    "message": "Address Added Successfully"
}
GET Remove Student Address {{url}}/dependants/remove-address/184c32e2-878d-4e89-99c3-91dda70c03e9/da879dcb-b062-462e-b935-5c1b879e3c0d ▸

Permanently deletes a saved address from a student's profile.

Path Parameters

  • id (string UUID, required): The student's UUID.
  • address_id (string UUID, required): UUID of the address to remove.

⚠️ Note on HTTP method

This is implemented as a GET request even though it performs a destructive delete — that's unusual REST design carried over from the existing API and worth being careful with (e.g. don't let link-prefetching or crawlers hit this URL). It cannot be undone once called.

Response

Empty data; message confirms the address was removed.

Auth
Bearer token
Used On
Student Profile
Sample Response (200 OK)
{
    "status": 200,
    "data": [],
    "message": "Address Removed Successfully"
}
POST Update Student Address {{url}}/dependants/update-address/184c32e2-878d-4e89-99c3-91dda70c03e9/93d41cd9-1b01-4bb3-95ce-56175ce7f493 ▸

Update the coordinates or primary flag on an existing student address.

Path Parameters

  • id (string UUID, required): The student's UUID.
  • address_id (string UUID, required): UUID of the address to update.

Request Body

  • latitude (number, required, range -90 to 90)
  • longitude (number, required, range -180 to 180)
  • is_primary (boolean, required)

Notes

  • Same primary-address exclusivity rule as Add Home Address: only one address per student can be primary.

Response

The updated address (data).

Auth
Bearer token
Request Body
{
    "latitude": -1.2921,
    "longitude": 36.8219,
    "is_primary": true //use only: true, false
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "uuid": "93d41cd9-1b01-4bb3-95ce-56175ce7f493",
        "is_primary": true,
        "latitude": -1.2921,
        "longitude": 36.8219
    },
    "message": "Address Updated Successfully"
}
GET List Students Without AccessLogs {{url}}/dependants/without-access-logs ▸

Retrieves a paginated list of students filtered by optional criteria such as tags, parent ID, or phone number. This endpoint is useful for applications that need to display or manage students associated with a parent entity (such as a user or account).

Parameters

  • tags (array[string], optional): List of tag UUIDs to filter students.
  • parent_id (string, optional): UUID of the parent entity to filter students.
  • phone_number (string, optional): Phone number to filter students.
  • per_page (integer, optional): Number of results per page. Default is 10.
  • page (integer, optional): Page number to retrieve. Default is 1.

Notes

  • All filter parameters are optional; omitting them returns all students.
  • Ensure the token environment variable is set with a valid bearer token.
  • The endpoint may return an empty array if no students match the filters.
Auth
Bearer token
Request Body
{
    "tags": ["d4b18b8f-eaa6-44e1-8655-d75f146c0933"], // filter by tag
    "status": "Checked Out", //Checked In, Checked Out or Denied
    "date_range": "2025-04-23 14:03:21, 2025-05-23 14:03:21",
    // "parent_id": "cf7a3821-e6be-490f-85b9-6f7ca3585aad", // filter by parent id
    // "phone_number": "+254733556677",  // filter by phone number
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "184c32e2-878d-4e89-99c3-91dda70c03e9",
            "first_name": "Simon",
            "middle_name": "Kimani",
            "last_name": "Chege",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2010-11-06 00:00:00",
            "gender": "Male",
            "third_party_id": "a2fce066-519c-4cba-968d-18aa70446411",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "cf7a3821-e6be-490f-85b9-6f7ca3585aad",
                "name": "Kevin Kariuki",
                "email": "kevin.kariuki@example.com",
                "phone": "+254733556677"
            },
            "guardians": [
                {
                    "uuid": "d651190e-5e68-43e0-82db-9c53426311ab",
                    "name": "Peter Chege"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-05 15:51:29",
            "tags": [
                {
                    "id": "d4b18b8f-eaa6-44e1-8655-d75f146c0933",
                    "name": "PM School Tag",
                    "description": "PM School Tag",
                    "entity": "universal",
                    "color_code": "#EA0D8D"
                }
            ],
            "iots": [
                {
                    "id": "44de4102-10cb-4df0-838d-ba5d7189d715",
                    "serial_number": "b923a161-df11-4479-ae88-baf42443566",
                    "code": "IOT-B20C4A9A46I",
                    "expires_at": "Mon, Jan 8, 2035 9:37 AM",
                    "validity": "8 years from now",
                    "iot_type": {
                        "id": "155c2ef7-d959-4e4b-82a6-a8035aed5a64",
                        "name": "nfc wristband"
                    },
                    "status": "Active",
                    "tags": []
                }
            ]
        },
        {
            "id": "0b1475e9-f811-4683-8a90-a94468dc7ef1",
            "first_name": "Junior",
            "middle_name": null,
            "last_name": "Pm",
            "phone": "",
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2005-01-05 00:00:00",
            "gender": "Female",
            "third_party_id": "2b8effd8-0782-4e66-b93f-d0ba8c4464c9",
            "is_active": 1,
            "metadata": {
                "grade": "8th Grade"
            },
            "parent": {
                "uuid": "d23b811d-368c-44fd-a031-6663bed28fc0",
                "name": "Pm Parent",
                "email": "Parent@gmail.com",
                "phone": "+254791472893"
            },
            "guardians": [
                {
                    "uuid": "41e5db5b-2ab2-4d8a-a8e2-6fe3fdaca078",
                    "name": "Nanny Guardian"
                },
                {
                    "uuid": "4d95c454-67aa-47ce-80c3-973f0d3750cb",
                    "name": "Maggy Grants"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2026-01-05 14:26:56",
            "tags": [
                {
                    "id": "d4b18b8f-eaa6-44e1-8655-d75f146c0933",
                    "name": "PM School Tag",
                    "description": "PM School Tag",
                    "entity": "universal",
                    "color_code": "#EA0D8D"
                },
                {
                    "id": "0655ca5b-1c6b-437d-b38a-7f4596fb038f",
                    "name": "Kiota School Rongai Route",
                    "description": "Kiota School Rongai Route for students",
                    "entity": "dependant",
                    "color_code": null
                }
            ]
        }
    ],
    "links": {
        "first": "http://terrago.test/api/dependants/without-access-logs?page=1",
        "last": "http://terrago.test/api/dependants/without-access-logs?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://terrago.test/api/dependants/without-access-logs?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "http://terrago.test/api/dependants/without-access-logs",
        "per_page": 10,
        "to": 2,
        "total": 2
    },
    "status": 200,
    "message": "Dependants Retrieved Successfully"
}
GET List Students Order By Route Ordering {{url}}/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82 ▸

Retrieves a paginated list of students filtered by optional criteria such as tags, parent ID, or phone number. This endpoint is useful for applications that need to display or manage students associated with a parent entity (such as a user or account).

Parameters

  • tags (array[string], optional): List of tag UUIDs to filter students.
  • parent_id (string, optional): UUID of the parent entity to filter students.
  • phone_number (string, optional): Phone number to filter students.
  • per_page (integer, optional): Number of results per page. Default is 10.
  • page (integer, optional): Page number to retrieve. Default is 1.

Notes

  • All filter parameters are optional; omitting them returns all students.
  • Ensure the token environment variable is set with a valid bearer token.
  • The endpoint may return an empty array if no students match the filters.
Auth
Bearer token
Used On
Route Profile
Request Body
{
    "order_by": "boarding_order", //alighting_order, boarding_order
    "order_direction": "asc", //asc, desc
    "trip_planner_id": "1742827f-ddf2-4894-ab72-60f0f93ba7ff",
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "c75f2355-2f88-40b2-916b-999744d1d1f5",
            "first_name": "Lincoln",
            "middle_name": "Hungi",
            "last_name": "Chege",
            "phone": "+254747337463",
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2010-11-06 00:00:00",
            "gender": "Male",
            "third_party_id": "61885c23-9e9c-49dd-8603-53fc14ae1950",
            "is_active": 1,
            "metadata": {
                "grade": "9th Grade"
            },
            "parent": {
                "uuid": "95db0ec4-83ab-4a7a-aff4-383e738e8d34",
                "name": "LaParent Ente",
                "email": "laparent@gmail.com",
                "phone": "+25470000001"
            },
            "guardians": [
                {
                    "uuid": "d651190e-5e68-43e0-82db-9c53426311ab",
                    "name": "Peter Chege"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-03 04:24:46",
            "addresses": [
                {
                    "id": "c7742a50-7f51-4a27-84bf-2db8a02b289b",
                    "latitude": -1.2674,
                    "longitude": 36.8079,
                    "is_primary": true
                },
                {
                    "id": "de4fbf8d-b827-4842-8ab5-e52d7fbda6ff",
                    "latitude": -1.2698,
                    "longitude": 36.8102,
                    "is_primary": false
                },
                {
                    "id": "e183966a-4cba-4bd4-ae6d-48956db5bd96",
                    "latitude": -1.2651,
                    "longitude": 36.8055,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "82bef288-61c8-4aa4-b31e-c258f0126259",
            "first_name": "Kids",
            "middle_name": "L",
            "last_name": "Name",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2018-12-03 00:00:00",
            "gender": "Female",
            "third_party_id": "6d024a1a-311f-48c4-9dbd-390b2554a252",
            "is_active": 1,
            "metadata": null,
            "parent": {
                "uuid": "9dcc2d36-5297-4c26-98db-660af8e00909",
                "name": "Le Parent",
                "email": "ling@gmqil.com",
                "phone": "+254700000111"
            },
            "guardians": [],
            "image": null,
            "notes": null,
            "created_at": "2025-12-03 05:16:54",
            "addresses": [
                {
                    "id": "8bcf2bda-f422-4c88-a731-23a3836be790",
                    "latitude": -1.3192,
                    "longitude": 36.7073,
                    "is_primary": true
                },
                {
                    "id": "048f1644-610f-4c47-b75f-4cee7536463a",
                    "latitude": -1.3215,
                    "longitude": 36.7098,
                    "is_primary": false
                },
                {
                    "id": "1ed720a9-46a0-489e-aa4d-a7e361e5d09f",
                    "latitude": -1.3168,
                    "longitude": 36.7051,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "184c32e2-878d-4e89-99c3-91dda70c03e9",
            "first_name": "Simon",
            "middle_name": "Kimani",
            "last_name": "Chege",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2010-11-06 00:00:00",
            "gender": "Male",
            "third_party_id": "a2fce066-519c-4cba-968d-18aa70446411",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "cf7a3821-e6be-490f-85b9-6f7ca3585aad",
                "name": "Kevin Kariuki",
                "email": "kevin.kariuki@example.com",
                "phone": "+254733556677"
            },
            "guardians": [
                {
                    "uuid": "d651190e-5e68-43e0-82db-9c53426311ab",
                    "name": "Peter Chege"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-05 15:51:29",
            "addresses": [
                {
                    "id": "b83c2cfc-1e20-4264-84b6-36ef72ae1fd3",
                    "latitude": -1.2893,
                    "longitude": 36.7837,
                    "is_primary": true
                },
                {
                    "id": "4a0ccaf4-bfdf-4ed2-ba2d-6ff4c6c13578",
                    "latitude": -1.2917,
                    "longitude": 36.7862,
                    "is_primary": false
                },
                {
                    "id": "66122fc7-f104-46b9-b6ab-286ab331ca5f",
                    "latitude": -1.2871,
                    "longitude": 36.7815,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "7dbdb6cc-6f7f-4cf9-884b-6b1032db8895",
            "first_name": "K34Kl",
            "middle_name": null,
            "last_name": "Kiddds",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2010-11-06 00:00:00",
            "gender": "Male",
            "third_party_id": "039467c3-7b50-4d62-a70b-6fd98393c2ae",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "2f41e784-9fe4-4bb3-9cae-c2592d8d0d6c",
                "name": "Linng Ladt",
                "email": "blackling20+0011@gmail.com",
                "phone": "+2547063473071"
            },
            "guardians": [
                {
                    "uuid": "a42beeee-7bbe-4eca-b88c-fdb177bf36b3",
                    "name": "Ling L"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-10 00:54:21",
            "addresses": [
                {
                    "id": "ae65f9ea-6ad4-426a-81fb-d9d408cb9924",
                    "latitude": -1.2801,
                    "longitude": 36.7712,
                    "is_primary": true
                },
                {
                    "id": "02f20a65-ef29-45a4-a99b-b3a2c784f3b0",
                    "latitude": -1.2825,
                    "longitude": 36.7736,
                    "is_primary": false
                },
                {
                    "id": "b6b6f3e5-00de-4c31-a23b-2c991e7ab0b5",
                    "latitude": -1.2779,
                    "longitude": 36.769,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "3fa67d4c-3654-45af-83e7-73ced7579d36",
            "first_name": "Kiddd",
            "middle_name": null,
            "last_name": "Kidd",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2017-12-11 00:00:00",
            "gender": "Male",
            "third_party_id": "6794a7e9-3179-47f6-97f4-9e4e65a706be",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "81ed76e7-bd5c-4cba-90d9-cffa34aa8dae",
                "name": "Kip Ling",
                "email": "blackling20+00041@gmail.com",
                "phone": "+2547942376841"
            },
            "guardians": [
                {
                    "uuid": "a42beeee-7bbe-4eca-b88c-fdb177bf36b3",
                    "name": "Ling L"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-11 15:15:34",
            "addresses": [
                {
                    "id": "5d156185-81ab-40d7-98df-47a78ac097b9",
                    "latitude": -1.2573,
                    "longitude": 36.8198,
                    "is_primary": true
                },
                {
                    "id": "a83fcf5f-452f-4994-83f3-a721120fd23e",
                    "latitude": -1.2597,
                    "longitude": 36.8221,
                    "is_primary": false
                },
                {
                    "id": "80176d42-0c42-4a84-9698-bf0085ff0f5f",
                    "latitude": -1.2549,
                    "longitude": 36.8175,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "a09b79af-552a-45d2-a020-70798466958d",
            "first_name": "PM",
            "middle_name": null,
            "last_name": "Mdogo",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2018-12-11 00:00:00",
            "gender": "Female",
            "third_party_id": "cbb727fb-1fcd-42b6-a78d-c3620025e1a1",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "a92b3004-4628-4ae4-9621-35ebe372ab47",
                "name": "PM Testing",
                "email": "tessdufysdt@gmail.com",
                "phone": "+254793453453"
            },
            "guardians": [],
            "image": null,
            "notes": null,
            "created_at": "2025-12-11 17:06:39",
            "addresses": [
                {
                    "id": "a6518223-d67d-427e-81c8-81ec0ab550de",
                    "latitude": -1.2143,
                    "longitude": 36.8021,
                    "is_primary": true
                },
                {
                    "id": "5792ed20-1cfe-4860-a715-f4a3758adfe9",
                    "latitude": -1.2167,
                    "longitude": 36.8045,
                    "is_primary": false
                },
                {
                    "id": "22375995-33e0-467d-9964-58c3b48db4d3",
                    "latitude": -1.2119,
                    "longitude": 36.7998,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "10f69867-18fa-4d03-a772-799b45ac9d01",
            "first_name": "John",
            "middle_name": null,
            "last_name": "Nyaberi",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2024-12-11 00:00:00",
            "gender": "Male",
            "third_party_id": "b7f5a95d-f404-44ba-8955-3f77e1606f7c",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "35438f0b-b488-4ea0-b69d-73e214910ab9",
                "name": "Erick Mwinyi",
                "email": "mwinyierick@gmail.com",
                "phone": "+254784976344"
            },
            "guardians": [],
            "image": null,
            "notes": null,
            "created_at": "2025-12-11 17:27:27",
            "addresses": [
                {
                    "id": "7c513985-28b4-41d0-af69-987abcb9481f",
                    "latitude": -1.2489,
                    "longitude": 36.8312,
                    "is_primary": true
                },
                {
                    "id": "28989fbe-780f-4929-84e2-ede5896cc480",
                    "latitude": -1.2513,
                    "longitude": 36.8336,
                    "is_primary": false
                },
                {
                    "id": "e7111c10-c512-40ba-8133-b6378160e84f",
                    "latitude": -1.2465,
                    "longitude": 36.8289,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "52e87b49-d8f8-4e91-a046-e3a4d4fe0a42",
            "first_name": "Kid2",
            "middle_name": null,
            "last_name": "Kiddds",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2010-11-06 00:00:00",
            "gender": "Male",
            "third_party_id": "d4de3465-ed17-4cca-8d07-8847f1dc4c26",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "81ed76e7-bd5c-4cba-90d9-cffa34aa8dae",
                "name": "Kip Ling",
                "email": "blackling20+00041@gmail.com",
                "phone": "+2547942376841"
            },
            "guardians": [
                {
                    "uuid": "9d618963-792a-47a9-89a4-5d8d1ff5420a",
                    "name": "Guardian1 Last"
                },
                {
                    "uuid": "24636b1b-8faa-4b9a-8cdf-62011dfe984d",
                    "name": "Kipps Guardiasn2"
                },
                {
                    "uuid": "a42beeee-7bbe-4eca-b88c-fdb177bf36b3",
                    "name": "Ling L"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-12 02:47:00",
            "addresses": [
                {
                    "id": "4add55ed-2659-412c-9f46-bd14b6bade88",
                    "latitude": -1.2298,
                    "longitude": 36.8056,
                    "is_primary": true
                },
                {
                    "id": "7224a555-8a60-47b1-bc78-6ad3185fc632",
                    "latitude": -1.2321,
                    "longitude": 36.8079,
                    "is_primary": false
                },
                {
                    "id": "f6b51e02-3b56-4af6-b43c-0755eff3654b",
                    "latitude": -1.2274,
                    "longitude": 36.8033,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "2788c72c-f6ed-451a-bd8f-a4aa52474eec",
            "first_name": "Kid3",
            "middle_name": "K",
            "last_name": "Last",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2020-12-12 00:00:00",
            "gender": "Female",
            "third_party_id": "62ce1ba2-6286-4b32-9b6f-46f495ed7926",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "81ed76e7-bd5c-4cba-90d9-cffa34aa8dae",
                "name": "Kip Ling",
                "email": "blackling20+00041@gmail.com",
                "phone": "+2547942376841"
            },
            "guardians": [
                {
                    "uuid": "24636b1b-8faa-4b9a-8cdf-62011dfe984d",
                    "name": "Kipps Guardiasn2"
                },
                {
                    "uuid": "9d618963-792a-47a9-89a4-5d8d1ff5420a",
                    "name": "Guardian1 Last"
                }
            ],
            "image": null,
            "notes": null,
            "created_at": "2025-12-12 04:51:00",
            "addresses": [
                {
                    "id": "17bf4d0d-95f5-4b5f-b9d7-6cac4a3d6e7b",
                    "latitude": -1.3089,
                    "longitude": 36.8321,
                    "is_primary": true
                },
                {
                    "id": "d5057d8f-3df5-4873-925e-9865e557118c",
                    "latitude": -1.3112,
                    "longitude": 36.8345,
                    "is_primary": false
                },
                {
                    "id": "5e034d69-22ca-4b5d-a07c-35d448f82de8",
                    "latitude": -1.3066,
                    "longitude": 36.8298,
                    "is_primary": false
                }
            ]
        },
        {
            "id": "2aa12867-4100-44c7-b31d-7d60726e0811",
            "first_name": "Ha",
            "middle_name": "rry",
            "last_name": "K",
            "phone": null,
            "email": null,
            "identification_document": null,
            "identification_number": null,
            "dob": "2001-11-01 00:00:00",
            "gender": "Male",
            "third_party_id": "d152ba99-9c04-4ca4-abac-ba8318b616a6",
            "is_active": 1,
            "metadata": {
                "grade": null
            },
            "parent": {
                "uuid": "9dcc2d36-5297-4c26-98db-660af8e00909",
                "name": "Le Parent",
                "email": "ling@gmqil.com",
                "phone": "+254700000111"
            },
            "guardians": [],
            "image": null,
            "notes": null,
            "created_at": "2025-12-12 13:42:12",
            "addresses": [
                {
                    "id": "f263996a-daef-4228-bc11-66c2bc9c8e59",
                    "latitude": -1.2812,
                    "longitude": 36.7798,
                    "is_primary": true
                },
                {
                    "id": "cfdae4c3-e811-48e5-8941-00b05db43f5d",
                    "latitude": -1.2836,
                    "longitude": 36.7821,
                    "is_primary": false
                },
                {
                    "id": "92d35c2f-0194-44ac-9c10-33773ca847a4",
                    "latitude": -1.2789,
                    "longitude": 36.7775,
                    "is_primary": false
                }
            ]
        }
    ],
    "links": {
        "first": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=1",
        "last": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=58",
        "prev": null,
        "next": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 58,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=2",
                "label": "2",
                "page": 2,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=3",
                "label": "3",
                "page": 3,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=4",
                "label": "4",
                "page": 4,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=5",
                "label": "5",
                "page": 5,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=6",
                "label": "6",
                "page": 6,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=7",
                "label": "7",
                "page": 7,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=8",
                "label": "8",
                "page": 8,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=9",
                "label": "9",
                "page": 9,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=10",
                "label": "10",
                "page": 10,
                "active": false
            },
            {
                "url": null,
                "label": "...",
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=57",
                "label": "57",
                "page": 57,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=58",
                "label": "58",
                "page": 58,
                "active": false
            },
            {
                "url": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82?page=2",
                "label": "Next »",
                "page": 2,
                "active": false
            }
        ],
        "path": "http://127.0.0.1:8000/api/dependants/route-order/2241ff88-f590-4fb1-9b99-18ecf15cfc82",
        "per_page": 10,
        "to": 10,
        "total": 580
    },
    "status": 200,
    "message": "Dependants Retrieved Successfully"
}
POST Record Trip Checkpoint (Pickup/Dropoff) {{url}}/trip-check-points ▸

Record the GPS location and time a student was picked up or dropped off during a specific trip. This is what powers the "actual pickup/dropoff location" feature shown to parents, separate from the scheduled route stops.

Request Body

  • dependant_id (string UUID, required): The child being picked up/dropped off.
  • trip_id (string UUID, required): The trip this checkpoint belongs to.
  • latitude (number, required, range -90 to 90)
  • longitude (number, required, range -180 to 180)
  • type (string, required): pickup or dropoff.
  • occurred_at (datetime, optional): Defaults to the current server time if omitted.

Notes

  • There can only be one pickup and one dropoff checkpoint per student per trip — submitting again for the same dependantid + tripid + type overwrites the previous value rather than creating a duplicate.
  • May trigger automatic home-address detection in the background if this looks like a recurring drop-off point.

Response

The recorded checkpoint (data) — student, trip, type (pickup/dropoff), coordinates and timestamp.

Auth
Bearer token (inherited)
Request Body
{
    "dependant_id": "3c8b5dac-c2d5-4697-ae87-ecae3bcf5e42",
    "trip_id": "5a766ea3-9697-4187-8458-0cc131698989", //trip uuid
    "latitude": -1.2833,
    "longitude": 36.8167,
    "type": "pickup", //use only: pickup or dropoff
    "occurred_at": "2026-05-05 19:00:00"
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "0adab1f1-01c7-46d3-8cb5-1cee43d09697",
        "type": "pickup",
        "latitude": -1.286389,
        "longitude": 36.817223,
        "occurred_at": "Tue, May 5, 2026 8:30 AM",
        "created_at": "Tue, May 5, 2026 10:20 AM",
        "dependant": {
            "id": "6c9c0aca-ec65-4dba-9717-f5a006d54503",
            "first_name": "Pink",
            "last_name": "Terra"
        },
        "trip": {
            "id": "5a766ea3-9697-4187-8458-0cc131698989",
            "waas_zone_name": "Demo Zone"
        }
    },
    "message": "Check point recorded successfully"
}
GET Get Trip Checkpoints by Trip {{url}}/trip-check-points/trip/5a766ea3-9697-4187-8458-0cc131698989 ▸

List the recorded pickup/dropoff checkpoints for every child on a given trip.

Path Parameters

  • tripId (string UUID, required): The trip's UUID.

Response

An array with one entry per student on the trip, each containing the student's basic info plus their pickup and dropoff checkpoint (either may be null if it hasn't happened yet).

Auth
Bearer token
Used On
Trip Monitoring
Sample Response (200 OK)
{
    "status": 200,
    "data": [
        {
            "dependant_id": "6c9c0aca-ec65-4dba-9717-f5a006d54503",
            "name": "Pink Terra",
            "pickup": {
                "id": "0adab1f1-01c7-46d3-8cb5-1cee43d09697",
                "latitude": -1.286389,
                "longitude": 36.817223,
                "occurred_at": "Tue, May 5, 2026 8:30 AM"
            },
            "dropoff": null
        }
    ],
    "message": "Trip check points retrieved successfully"
}
GET Get Trip Checkpoints by Student {{url}}/trip-check-points/dependant/6c9c0aca-ec65-4dba-9717-f5a006d54503 ▸

List a single child's pickup/dropoff checkpoint history across all of their trips, most recent first. Useful for a parent-facing "trip history" view.

Path Parameters

  • dependantId (string UUID, required): The student's UUID.

Response

An array with one entry per trip the student appears on, containing the trip ID, zone/location name, and the pickup/dropoff checkpoint for that trip (either may be null).

Auth
Bearer token
Sample Response (200 OK)
{
    "status": 200,
    "data": [
        {
            "trip_id": "5a766ea3-9697-4187-8458-0cc131698989",
            "waas_zone_name": "Demo Zone",
            "pickup": {
                "latitude": -1.286389,
                "longitude": 36.817223,
                "occurred_at": "2026-05-05 08:30:00"
            },
            "dropoff": null
        }
    ],
    "message": "Dependant check points retrieved successfully"
}
GET List Trip Planner Assignments {{url}}/dependants/184c32e2-878d-4e89-99c3-91dda70c03e9/trip-planners ▸

List the trip planners a student is assigned to. Assignments live in the dependantrouteorders pivot (the same mapping the Save Boarding/Alighting Order screen writes), so a student can belong to several planners — e.g. a morning run and a return run — each scoped to a route.

Path Parameters

  • id (string UUID, required): The student's UUID.

Response

Array of assignments, each: id (assignment uuid — used to unassign), boardingorder, alightingorder, tripplanner (id, label, direction, starttime, status), route (id, name).

Notes

  • This mapping is what GET /api/v2/students?tripplannerid= filters the driver-app roster by.
  • Requires a bearer token (auth:api).
Auth
Bearer token
POST Assign Trip Planner {{url}}/dependants/184c32e2-878d-4e89-99c3-91dda70c03e9/trip-planners ▸

Assign a student to a trip planner on a specific route. Appends them to the end of that (route, planner) boarding/alighting order. Idempotent — assigning the same (student, route, planner) again returns the existing assignment instead of duplicating it. The Save Boarding/Alighting Order screen can later re-order them.

Path Parameters

  • id (string UUID, required): The student's UUID.

Request Body

  • tripplannerid (string UUID, required): The trip planner's UUID (exists:trip_planners,uuid).
  • route_id (string UUID, required): The route's UUID (exists:routes,uuid). The route must carry a the registry tag.

Response

{ "id": "<assignment uuid>" }.

Notes

  • Boarding & alighting order default to max + 1 for that (route, planner).
  • Invalidates the cached the registry roster for the route's tag so the driver app re-fetches.
  • Requires a bearer token (auth:api).
Auth
Bearer token
Request Body
{
    "trip_planner_id": "da2175e7-cc4d-4c25-a8e8-4ad81300a9e1",  // Trip planner UUID (which trip this belongs to)
    "route_id": "643ab899-5b74-4dc1-b3a0-5b512dc11336"  // Route UUID
}
DELETE Unassign Trip Planner {{url}}/dependants/184c32e2-878d-4e89-99c3-91dda70c03e9/trip-planners/{assignmentId} ▸

Remove a single trip-planner assignment (one dependantrouteorders row, identified by its assignment uuid).

Path Parameters

  • id (string UUID, required): The student's UUID.
  • assignmentId (string UUID, required): The assignment id returned by List Trip Planner Assignments.

Notes

  • Returns 404 if the assignment doesn't exist or doesn't belong to this student.
  • Invalidates the cached the registry roster for the route's tag.
  • Requires a bearer token (auth:api).
Auth
Bearer token
DELETE Delete {{url}}/dependants/delete/c3d4e5f6-0000-4a11-8888-abcde1234567 ▸

Delete a student (dependant) record.

Notes

  • Requires a bearer token (auth:api).
Auth
Bearer token
Sample Response (200 OK)
{
    "status": 200,
    "data": [],
    "message": "Dependant Deleted Successfully"
}