Guardian API Documentation

The Guardian API is the public API that the Guardian App uses to let parents and guardians register, log in, link their children, monitor school attendance, and receive notifications.

Overview

Guardians use the Guardian App to:

Register an account and log in with their email and password
Link one or more students to their account
See each student's current in-school / out-of-school status
Browse attendance check-in and check-out logs
Read notifications (attendance alerts, announcements, emergencies, reminders)
Manage their profile, change their password, and register their device for push notifications

Base Path

All guardian endpoints are served under:

/api/public/school-guardian

A few account endpoints (change password, device token, token refresh) are served under /api/guardian instead — these are called out individually below.

Response Format

Every response uses the same envelope:

{
        "success": true,
        "data": { },
        "error": null,
        "metadata": {
          "timestamp": "...",
          "version": "...",
          "requestId": "..."
        }
      }

On failure, success is false and error carries a code, message, and optional details.

Authentication

After login or registration the app receives a token and sends it on every subsequent request as a bearer token:

Authorization: Bearer <token>

If a request returns 401 Unauthorized, the app attempts to refresh the token via POST /api/guardian/auth/refresh-token with { "refreshToken": "..." }; if that fails the guardian is sent back to the login screen.

Register

POST /api/public/school-guardian/auth/register

Field	Required	Notes
`firstName`	Yes
`lastName`	Yes
`middleName`	No
`dateOfBirth`	Yes	`YYYY-MM-DD`
`email`	Yes
`password`	Yes
`contactNumber`	Yes	10 digits starting with 9 (Philippine format)
`alternateNumber`	No
`address`	No
`occupation`	No

Returns the same payload as Login.

POST /api/public/school-guardian/auth/login

Field	Required	Notes
`email`	Yes
`password`	Yes
`deviceId`	No
`deviceToken`	No	FCM/APNS push token (mobile apps)
`platform`	No	`ios`, `android`, or `web`

Response (data):

{
        "token": "...",
        "guardian": {
          "id": "...",
          "firstName": "...",
          "lastName": "...",
          "email": "...",
          "phoneNumber": "..."
        },
        "students": [ ],
        "permissions": [ ],
        "company": {
          "id": 1,
          "name": "...",
          "logoUrl": "..."
        }
      }

Logout

POST /api/public/school-guardian/auth/logout

Invalidates the session server-side. The app clears its stored tokens regardless of the result.

Change Password

POST /api/guardian/auth/change-password

Field	Required
`currentPassword`	Yes
`newPassword`	Yes

Students

Get My Students

GET /api/public/school-guardian/students

Returns all students linked to the guardian. Each student includes name, studentNumber, gender, date of birth, section (with grade level, adviser, school year), LRN, profile photo, and the guardian's relationship / isPrimary flags.

Preview a Student

GET /api/public/school-guardian/students/preview?studentId=<id>

Returns a lightweight preview (name, student number, gender, section, grade level, photo) so the guardian can confirm the student before adding them.

Add a Student

POST /api/public/school-guardian/students/add

Field	Required	Notes
`studentId`	One of `studentId` / `studentCode`
`studentCode`	One of `studentId` / `studentCode`
`relationship`	No	e.g. parent, guardian

Links the student to the guardian's account.

Remove a Student

DELETE /api/public/school-guardian/students/{studentId}

Unlinks the student from the guardian's account.

Attendance

Get Attendance Status

GET /api/public/school-guardian/attendance/status

Returns the current status of every linked student.

[
        {
          "studentId": "...",
          "studentName": "...",
          "studentCode": "...",
          "status": "in-school",
          "photoUrl": "...",
          "lastCheckIn": { "timestamp": "...", "gate": "...", "photo": "..." },
          "lastCheckOut": { "timestamp": "...", "gate": "...", "photo": "..." },
          "todayAttendance": {
            "checkIns": 1,
            "checkOuts": 0,
            "totalTime": "...",
            "firstCheckIn": "...",
            "lastCheckOut": "..."
          }
        }
      ]

status is one of in-school, out-of-school, or unknown.

Get Attendance Logs

GET /api/public/school-guardian/attendance/logs

Query parameters (all optional):

studentId — filter to one student
limit, offset — pagination
days — look-back window in days
startDate, endDate — explicit date range
type — check-in, check-out, or all

Response (data): { "logs": [ ], "total": <number> }. Each log entry contains id, studentId, studentName, type (check-in / check-out), timestamp, gate ({ id, name }), and an optional photo.

Notifications

Get Notifications

GET /api/public/school-guardian/notifications

Query parameters (all optional):

limit, offset — pagination
type — attendance, announcement, emergency, reminder, or all
unreadOnly — true to return only unread items
studentId — filter to one student
priority — low, medium, high, or urgent

Response (data): { "notifications": [ ], "total": <number>, "unreadCount": <number> }. Each notification contains id, type, title, message, timestamp, isRead, priority, and optional studentId, studentName, actionUrl, and data.

Mark Notifications as Read

POST /api/public/school-guardian/notifications/read

{ "notificationIds": ["...", "..."] }

Profile

Get Profile

GET /api/public/school-guardian/profile

Returns the guardian's profile, including their linked students, lastLogin / lastAppLogin, preferredLanguage, activeDevices, profile photo, and notification preferences.

Update Profile

PUT /api/public/school-guardian/profile

All fields are optional; send only the ones being changed:

firstName, lastName, middleName, email, phoneNumber, address, occupation, preferredLanguage.

Upload Profile Photo

POST /api/public/school-guardian/profile/photo

Sent as multipart/form-data with the image in the photo field. Returns the updated profile.

Push Notifications (Device Token)

Register Device Token

POST /api/guardian/device-token

{
        "token": "<fcm-or-apns-token>",
        "platform": "android",
        "deviceId": "<device-id>"
      }

platform is ios, android, or web. The app retries registration up to 3 times.

Check Device Token Status

GET /api/guardian/device-token/status

Returns whether the current device is registered for push ({ registered, deviceInfo, lastCheckedAt }).

Remove Device Token

DELETE /api/guardian/device-token/{token}

Unregisters the device so it stops receiving push notifications.

Reference Values

Attendance status (attendance/status): in-school, out-of-school, unknown.

Attendance log / filter type: check-in, check-out, all.

Notification type: attendance, announcement, emergency, reminder, general.

Notification priority: low, medium, high, urgent.

Platform: ios, android, web.

Push Notifications — notification setup

Guardian API Documentation#

Overview#

Base Path#

Response Format#

Authentication#

Register#

Login#

Logout#

Change Password#

Students#

Get My Students#

Preview a Student#

Add a Student#

Remove a Student#

Attendance#

Get Attendance Status#

Get Attendance Logs#

Notifications#

Get Notifications#

Mark Notifications as Read#

Profile#

Get Profile#

Update Profile#

Upload Profile Photo#

Push Notifications (Device Token)#

Register Device Token#

Check Device Token Status#

Remove Device Token#

Reference Values#

Related Pages#