Guardians

Alternate authorized adults, besides the parent, permitted to drop off or collect a child. Endpoints to create, update, view and delete a guardian, and to sync the guardian↔student relationships that control who may pick up which student.

5 endpoint(s)

GET List {{url}}/guardians ▸

Retrieves a list of guardians from the system.

Endpoint: GET {{url}}/guardians

Description: Returns an array of guardian objects. This endpoint is typically used to fetch all guardians registered in the system.

Parameters:

No query or path parameters are required for this request.

Authentication:

Requires a valid authentication token (usually provided in the token variable or as a header).
The Accept: application/json header must be set.

Sample Response:

[
  {
    "id": "string",
    "name": "string",
    "email": "string",
    "phone": "string",
    // ... other guardian fields
  }
]

Auth

Bearer token

Sample Response (200 OK)

{
    "data": [
        {
            "id": "d651190e-5e68-43e0-82db-9c53426311ab",
            "first_name": "Peter",
            "middle_name": "Kimani",
            "last_name": "Chege",
            "email": null,
            "phone": "+254722626879",
            "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"
        }
    ],
    "links": {
        "first": "https://terragostg.terrasofthq.com/api/guardians?page=1",
        "last": "https://terragostg.terrasofthq.com/api/guardians?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://terragostg.terrasofthq.com/api/guardians?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "page": null,
                "active": false
            }
        ],
        "path": "https://terragostg.terrasofthq.com/api/guardians",
        "per_page": 15,
        "to": 1,
        "total": 1
    },
    "status": 200,
    "message": "Guardians Retrieved Successfully"
}

POST Add {{url}}/guardians/add ▸

Creates a new guardian record in the system.

Sample request body:

first_name: Guardian's first name (string)

middle_name: Guardian's middle name (string)

last_name: Guardian's last name (string)

dob: Date of birth in DD-MM-YYYY format (string)

gender: Gender of the guardian. Allowed values: MALE, FEMALE, OTHER, N/A (string)

Response

The created guardian (data).

Auth

Bearer token

Request Body

{
    "first_name" : "Peter",
    "middle_name": "Kimani",
    "last_name" : "Chege",
    "dob":"06-11-2000",
    "gender": "MALE", //only use: MALE, FEMALE, OTHER, N/A
    "phone" : "+254722626879",
    "identification_document": "national_id",
    "identification_number": "36898912",
    "parent_id" : "cf7a3821-e6be-490f-85b9-6f7ca3585aad"
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "id": "d651190e-5e68-43e0-82db-9c53426311ab",
        "first_name": "Peter",
        "middle_name": "Kimani",
        "last_name": "Chege",
        "email": null,
        "phone": "+254722626879",
        "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": "Guardian Created Successfully"
}

PUT Update {{url}}/guardians/update/d651190e-5e68-43e0-82db-9c53426311ab ▸

Update an existing guardian's details (an alternate person, besides the parent, authorized to drop off/collect a child).

Path Parameters

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

Request Body

parent_id (string UUID, required): The parent user this guardian belongs to.
firstname, lastname (string, required); middle_name (optional).
email, phone (optional).
dob (string, optional): Date of birth.
gender (string, required): Mapped via Guardian::GENDER.
identificationdocument / identificationnumber (optional).

Response

The updated guardian (GuardianResource).

Notes

Returns 404 if the guardian UUID doesn't exist.
Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "first_name" : "Peter",
    "middle_name": "Kimani",
    "last_name" : "Chege",
    "dob":"06-11-2000",
    "gender": "MALE", //only use: MALE, FEMALE, OTHER, N/A
    "phone" : "+254722626879",
    "identification_document": "national_id",
    "identification_number": "36898912",
    "parent_id" : "cf7a3821-e6be-490f-85b9-6f7ca3585aad"
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "id": "d651190e-5e68-43e0-82db-9c53426311ab",
        "first_name": "Peter",
        "middle_name": "Kimani",
        "last_name": "Chege",
        "email": null,
        "phone": "+254722626879",
        "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": "Guardian Updated Successfully"
}

GET Show {{url}}/guardians/ba20fb10-c2c1-4951-9903-53c6fdbeabef ▸

Retrieve a single guardian by UUID.

Path Parameters

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

Response

The guardian record (GuardianResource).

Notes

Returns 404 if no guardian matches the UUID.
Requires a bearer token (auth:api).

Auth

Bearer token

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "id": "d651190e-5e68-43e0-82db-9c53426311ab",
        "first_name": "Peter",
        "middle_name": "Kimani",
        "last_name": "Chege",
        "email": null,
        "phone": "+254722626879",
        "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": "Guardian Retrieved Successfully"
}

POST SyncDependants {{url}}/guardians/sync-dependants/d651190e-5e68-43e0-82db-9c53426311ab ▸

Set which students (children) a guardian is linked to. This is a full replacement sync of the guardian↔student relationship: students not included in the request are unlinked, and new ones are linked.

Path Parameters

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

Request Body

students (array, required): List of student UUIDs to link. Each must exist (exists:students,uuid).

Response

The guardian's resulting set of linked students (DependantResource collection).

Notes

Passing an empty/omitted list fails validation (students is required).
Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "dependants": ["184c32e2-878d-4e89-99c3-91dda70c03e9"]  // List of student UUIDs to link
}

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": "dependants synced Successfully"
}