P

PNRC Nursing E-Logbook — API Reference

Complete documentation of all 210 backend APIs, flows, payloads, and validation rules

Total APIs: 210
Modules: 19
Auth: JWT Cookie & Bearer
🔍

1. Authentication & Session Security

Core session initialization, credential validation, JWT token exchange, impersonation, and logout workflows.

11 APIs
POST /api/auth/login — User Login & Session Creation
🌐 Public Public / Any registered user
API Purpose: Authenticates an existing user via normalized email and password. Generates a secure JWT token stored in an httpOnly cookie (and returned as session payload), records login activity, and verifies institutional tenancy.

📍 Website Flow Placement

First step in the user journey. Invoked from the login screen (`/login`). Upon success, redirects users to their role-specific dashboard (`/student`, `/supervisor`, `/coordinator`, `/principal`, etc.).

🔗 Dependencies & Prerequisites

Requires user account to exist in `users` and `profiles` tables.

⚖️ Validation & Business Rules

Enforces brute-force rate limiting (5 attempts per 15 min). Passwords checked using bcrypt.compare. Returns `force_password_change` flag if first-time or temporary password is active.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Registered email address (case-insensitive, normalized).
password string YES Plaintext account password (evaluated against bcrypt hash).
Example Request Payload (JSON)
{
  "email": "student@example.com",
  "password": "SecurePassword123!"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Login successful; JWT cookie set and user profile returned.
400 Missing email or password in request body.
401 Invalid credentials or incorrect password.
403 Account is inactive, suspended, or pending verification.
429 Rate limit exceeded (too many failed attempts).
500 Server or database error during authentication.
Response Payload Structure
Field Type Description
user.id string (UUID) Unique identifier of the authenticated user.
user.email string Verified email address.
user.full_name string Display name of the user.
user.role string Assigned role: student, supervisor, coordinator, principal, hod, college_admin, hospital_admin, superadmin.
user.college_id string (UUID) | null Associated college institution ID.
user.department_id string (UUID) | null Associated academic department ID.
flags.force_password_change boolean True if user must set a new password before accessing portal.
flags.requires_profile_completion boolean True if mandatory demographic/KYC fields are missing.
Example Success Response (JSON)
{
  "user": {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "email": "student@example.com",
    "full_name": "Simran Kaur",
    "role": "student",
    "college_id": "c-10293847-56ba-4e99-8102-aabbccddeeff",
    "department_id": "d-55667788-9900-4112-9988-112233445566"
  },
  "flags": {
    "force_password_change": false,
    "requires_profile_completion": false
  }
}
GET /api/auth/me — Get Current Authenticated Session
🔒 Auth All Authenticated Roles
API Purpose: Validates the active session JWT token from cookie or Bearer header, returns user role, profile IDs, and setup flags.

📍 Website Flow Placement

Executed on every initial SPA load, page refresh, and router guard check to rehydrate user state.

🔗 Dependencies & Prerequisites

Requires active JWT cookie or Authorization header from previous login.

⚖️ Validation & Business Rules

Token signature verified with JWT_SECRET. Inactive users receive 401 with immediate logout trigger.

📥 Request Specification

Required Headers
Authorization: Bearer <token> Cookie: jwt=<token>
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Active session valid; returns user object.
401 Token missing, expired, or invalid.
500 Server error.
Response Payload Structure
Field Type Description
user.id string User ID.
user.email string User email address.
user.full_name string User full name.
user.role string User primary system role.
user.college_id string | null Institutional college ID.
user.department_id string | null Department ID.
flags.force_password_change boolean Whether password reset is mandated.
flags.requires_profile_completion boolean Whether student/staff profile setup is incomplete.
Example Success Response (JSON)
{
  "user": {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "email": "student@example.com",
    "full_name": "Simran Kaur",
    "role": "student",
    "college_id": "c-10293847-56ba-4e99-8102-aabbccddeeff",
    "department_id": "d-55667788-9900-4112-9988-112233445566"
  },
  "flags": {
    "force_password_change": false,
    "requires_profile_completion": false
  }
}
POST /api/auth/refresh — Refresh Session Token
🔒 Auth All Authenticated Roles
API Purpose: Refreshes an expiring access token and issues a refreshed JWT cookie without requiring credential re-entry.

📍 Website Flow Placement

Triggered silently by the frontend HTTP interceptor upon receiving a 401 status on authenticated requests.

🔗 Dependencies & Prerequisites

Requires existing refresh token stored in browser cookie.

⚖️ Validation & Business Rules

Rotates refresh token and sets new expiry timestamp.

📥 Request Specification

Required Headers
Content-Type: application/json
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Session refreshed successfully; new cookie attached.
401 Refresh token missing, revoked, or expired.
500 Internal server error.
Response Payload Structure
Field Type Description
user object Refreshed user profile object.
Example Success Response (JSON)
{
  "user": {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "email": "student@example.com",
    "full_name": "Simran Kaur",
    "role": "student"
  }
}
POST /api/auth/logout — User Logout
🌐 Public All Roles
API Purpose: Terminates current session, invalidates active JWT cookie, and removes token from client.

📍 Website Flow Placement

Invoked when user clicks 'Logout' from navigation bar or user dropdown menu.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Clears `jwt` and `jwt_refresh` cookies by setting expiration to past epoch.

📥 Request Specification

Required Headers
None required
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
204 Logout successful; auth cookies cleared.
Returns empty body (e.g. 204 No Content).
POST /api/auth/logout-all — Terminate All Active Sessions
🔒 Auth All Authenticated Roles
API Purpose: Invalidates all active tokens and sessions across all devices for the authenticated user.

📍 Website Flow Placement

Triggered from User Account Security / Sessions settings page.

🔗 Dependencies & Prerequisites

Requires active authenticated session.

⚖️ Validation & Business Rules

Increments user `token_version` in DB, instantly invalidating all previously minted JWTs.

📥 Request Specification

Required Headers
Authorization: Bearer <token>
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
204 All sessions terminated.
401 Unauthorized.
Returns empty body (e.g. 204 No Content).
GET /api/auth/sessions — List Active User Sessions
🔒 Auth All Authenticated Roles
API Purpose: Retrieves metadata of all active devices and browser sessions registered for the authenticated user.

📍 Website Flow Placement

Security tab in User Profile settings.

🔗 Dependencies & Prerequisites

Requires authenticated session.

⚖️ Validation & Business Rules

Masks sensitive IP segments if privacy flags are enabled.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Active sessions list returned.
401 Unauthorized.
Response Payload Structure
Field Type Description
[].id string Session record ID.
[].ip_address string Client IP.
[].user_agent string Browser user agent string.
[].last_activity string (ISO Date) Timestamp of last request.
[].is_current boolean Whether this session matches current request.
Example Success Response (JSON)
[
  {
    "id": "sess-8812-4411",
    "ip_address": "103.21.144.10",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/128.0.0.0",
    "last_activity": "2026-09-29T09:30:00.000Z",
    "is_current": true
  }
]
DELETE /api/auth/sessions/:id — Revoke Specific Session
🔒 Auth All Authenticated Roles
API Purpose: Remotely terminates a specific active device session by session ID.

📍 Website Flow Placement

Invoked when user clicks 'Revoke Device' on the sessions list.

🔗 Dependencies & Prerequisites

Requires target session to belong to the authenticated user.

⚖️ Validation & Business Rules

Cannot revoke another user's session.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Session identifier to revoke.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
204 Session revoked successfully.
401 Unauthorized.
404 Session not found.
Returns empty body (e.g. 204 No Content).
POST /api/auth/impersonate — Superadmin User Impersonation
🔒 Auth superadmin
API Purpose: Allows Superadmin to assume identity of any user (student, supervisor, coordinator, principal) for debugging or administrative audit.

📍 Website Flow Placement

Triggered from Superadmin User Management panel via 'Impersonate' button.

🔗 Dependencies & Prerequisites

Requires target user account to exist and be active.

⚖️ Validation & Business Rules

Full audit trail logged with superadmin ID, target user ID, IP address, and timestamp.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
userId string (UUID) YES Target user ID to impersonate.
password string YES Superadmin's current password for re-authentication confirmation.
Example Request Payload (JSON)
{
  "userId": "u-94820f12-88aa-4e12-b231-104928adbeef",
  "password": "SuperAdminMasterPassword!"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Impersonation session established.
401 Superadmin re-authentication password failed.
403 Non-superadmin role attempted impersonation.
404 Target user ID not found or inactive.
Response Payload Structure
Field Type Description
success boolean Operation outcome.
user object Target user profile object with impersonated claims.
Example Success Response (JSON)
{
  "success": true,
  "user": {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "email": "student@example.com",
    "full_name": "Simran Kaur",
    "role": "student",
    "impersonated_by": "superadmin-master-id"
  }
}
POST /api/auth/signup — Direct Signup Guard (Redirector)
🌐 Public Public
API Purpose: Deprecation barrier returning HTTP 410 redirecting open registrations to the verified registration request flow.

📍 Website Flow Placement

Legacy safety guard.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Direct open signups without verification are blocked.

📥 Request Specification

Required Headers
None required
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
410 Direct signup discontinued in favor of external verification.
Response Payload Structure
Field Type Description
error string Guidance to use registration request workflow.
Example Success Response (JSON)
{
  "error": "Use the registration request workflow"
}
POST /api/auth/reset-password — Direct Password Reset Guard
🌐 Public Public
API Purpose: Guards against unverified password overwrites; guides callers to use OTP verification.

📍 Website Flow Placement

Legacy safety guard.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Direct password overwrite without OTP token is rejected.

📥 Request Specification

Required Headers
None required
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
410 Endpoint migrated to OTP-verified flow.
Response Payload Structure
Field Type Description
error string Instructional error message.
Example Success Response (JSON)
{
  "error": "Use the verified password-reset workflow"
}
POST /api/auth/register-request — Submit Staff / Student Registration Request
🌐 Public Public
API Purpose: Creates a pending institutional registration request for staff (supervisors, coordinators, principals) or students needing manual approval.

📍 Website Flow Placement

Triggered on `/register` page when staff members sign up. Awaits Year Coordinator or Principal approval.

🔗 Dependencies & Prerequisites

Requires valid college/department reference.

⚖️ Validation & Business Rules

Stores password as bcrypt hash in `registration_requests` table. Prevents enumeration by returning generic acknowledgement.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Applicant's official email.
password string YES Proposed account password.
full_name string YES Full legal name.
role string YES Requested role: supervisor, coordinator, principal, student.
college_id string (UUID) OPT College affiliation ID.
department_id string (UUID) OPT Department ID.
hospital_id string (UUID) OPT Hospital ID if clinical supervisor.
enrollment_no string OPT PNRC Roll / Enrollment number (for students).
Example Request Payload (JSON)
{
  "email": "teacher.manpreet@college.edu",
  "password": "TeacherStrongPass1!",
  "full_name": "Dr. Manpreet Singh",
  "role": "supervisor",
  "college_id": "c-10293847-56ba-4e99-8102-aabbccddeeff",
  "department_id": "d-55667788-9900-4112-9988-112233445566"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Request logged for administrative verification.
400 Missing mandatory fields or invalid format.
409 Email already registered.
Response Payload Structure
Field Type Description
success boolean Request status.
message string Acknowledgement notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "If eligible, the registration request will be reviewed."
}

2. Account Registration, External Verification & Student Activation

Multi-step student verification through the external council API, account activation, first-time OTP generation, and administrative approvals.

8 APIs
POST /api/auth/verify-external-student — Verify & Provision External Student Account
🌐 Public Public / Student Applicant
API Purpose: Validates student credentials against the external Punjab Nurses Registration Council (PNRC) student database. If verified, automatically provisions the student profile, maps course code (83->GNM, 82->ANM), assigns Year 1 enrollment, and generates a first-time activation OTP.

📍 Website Flow Placement

Primary entry point on the student activation screen (`/activate`). Initiates the student onboarding workflow.

🔗 Dependencies & Prerequisites

Calls external council API service (`studentProvisioningService.js`). Matches courses via `course_external_mappings` table.

⚖️ Validation & Business Rules

External passwords are never stored. Creates user with `force_password_change = 1`. Creates `student_academic_enrollments` record for Year 1. Sends 6-digit cryptographic OTP.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
enrollmentNo string YES Official PNRC student enrollment/roll number.
mobile string YES 10-digit mobile number matching external registration.
email string YES Email address matching external registration.
Example Request Payload (JSON)
{
  "enrollmentNo": "155854",
  "mobile": "7018619880",
  "email": "akash.veritos@gmail.com"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Student verified and provisioned; OTP dispatched.
400 Missing or malformed enrollment number, mobile, or email.
404 No student found matching credentials on external council database.
502 External council verification service unavailable.
500 Internal database provisioning error.
Response Payload Structure
Field Type Description
success boolean Indicates verification and provisioning status.
message string Status message.
studentCode number External council student code.
fullName string Student legal name from council records.
fatherName string Father's name.
motherName string Mother's name.
courseName string Resolved course name (e.g. GNM, ANM).
courseId string (UUID) Internal course ID.
academicYear number Initial academic year (Year 1).
email string Masked or confirmed email where OTP was dispatched.
requiresFirstTimeSetup boolean True if student must complete OTP and password setup.
Example Success Response (JSON)
{
  "success": true,
  "message": "Student verified successfully. A 6-digit OTP has been sent to your email.",
  "studentCode": 155854,
  "fullName": "TestSushanVeritos",
  "fatherName": "TestingFatherName",
  "motherName": "KRISHNA RANI",
  "courseName": "General Nursing and Midwifery (GNM)",
  "courseId": "c-gnm-4411-8899-0011",
  "academicYear": 1,
  "email": "akash.veritos@gmail.com",
  "requiresFirstTimeSetup": true
}
POST /api/auth/check-account-status — Check Account Setup Status
🌐 Public Public
API Purpose: Determines whether an email address belongs to an existing account, and whether it requires first-time OTP verification, password change, or normal login.

📍 Website Flow Placement

Used by the activation modal to determine whether to prompt for OTP or direct the student to sign in.

🔗 Dependencies & Prerequisites

Requires user record in `users` table.

⚖️ Validation & Business Rules

Normalized lowercase email lookup.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Email address to check.
Example Request Payload (JSON)
{
  "email": "akash.veritos@gmail.com"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Account status evaluated successfully.
400 Invalid email format.
404 Email address not found in system.
Response Payload Structure
Field Type Description
exists boolean Whether account exists.
status string Status: 'requires_setup', 'ready', 'inactive'.
requiresFirstTimeSetup boolean Whether first-time OTP and password setup is needed.
hasPendingOtp boolean Whether an unexpired OTP is waiting.
Example Success Response (JSON)
{
  "exists": true,
  "status": "requires_setup",
  "requiresFirstTimeSetup": true,
  "hasPendingOtp": true
}
POST /api/auth/verify-first-time-otp — Verify First-Time Activation OTP
🌐 Public Public / Provisioned Student
API Purpose: Validates the 6-digit OTP code sent to the student's email during external account verification.

📍 Website Flow Placement

Step 2 of student account activation. Follows `/api/auth/verify-external-student`.

🔗 Dependencies & Prerequisites

Requires pending OTP stored in user's `reset_otp` column.

⚖️ Validation & Business Rules

OTP validated using constant-time hash comparison (`safeHashEqual`). Expires after 15 minutes.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Student email address.
otp string YES 6-digit verification code.
Example Request Payload (JSON)
{
  "email": "akash.veritos@gmail.com",
  "otp": "482910"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 OTP verified.
400 Invalid or expired OTP code (must be 6 digits and within 15 min window).
404 Account not found.
Response Payload Structure
Field Type Description
success boolean Verification outcome.
message string Confirmation instructions.
Example Success Response (JSON)
{
  "success": true,
  "message": "OTP verified successfully. Please set your new password."
}
POST /api/auth/resend-first-time-otp — Resend First-Time Activation OTP
🌐 Public Public / Provisioned Student
API Purpose: Generates and dispatches a fresh 6-digit OTP code to the student's email if the previous code expired or was not received.

📍 Website Flow Placement

Triggered when user clicks 'Resend OTP' link on activation screen.

🔗 Dependencies & Prerequisites

Requires account in `requires_setup` state.

⚖️ Validation & Business Rules

Enforces 60-second cooldown period between successive OTP requests.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Student email address.
Example Request Payload (JSON)
{
  "email": "akash.veritos@gmail.com"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Fresh OTP dispatched to student email.
400 Account already completed setup or invalid email.
404 Account not found.
429 Rate limit: must wait 60 seconds before requesting another code.
Response Payload Structure
Field Type Description
success boolean Dispatch outcome.
message string Status message.
Example Success Response (JSON)
{
  "success": true,
  "message": "A new 6-digit OTP has been sent to your email."
}
POST /api/auth/complete-first-time-setup — Complete First-Time Setup & Set Password
🌐 Public Public / Provisioned Student
API Purpose: Finalizes activation by verifying the OTP, hashing and saving the student's permanent password, clearing setup flags, and returning an active login session.

📍 Website Flow Placement

Final step of student account activation. Redirects to `/student` dashboard upon success.

🔗 Dependencies & Prerequisites

Requires valid unexpired OTP from verification step.

⚖️ Validation & Business Rules

Sets `force_password_change = 0`, sets `is_active = 1`, clears `reset_otp`, and issues httpOnly JWT session cookie.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Student email address.
otp string YES 6-digit OTP code.
newPassword string YES New password (min 8 chars, uppercase, lowercase, number, symbol).
Example Request Payload (JSON)
{
  "email": "akash.veritos@gmail.com",
  "otp": "482910",
  "newPassword": "StudentPermanentPassword2026!"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Setup completed successfully; student logged in.
400 Invalid OTP, expired code, or weak password.
404 Account not found.
Response Payload Structure
Field Type Description
success boolean Setup completion status.
message string Success notification.
user object Newly activated user profile.
Example Success Response (JSON)
{
  "success": true,
  "message": "Account setup complete. Welcome to PNRC Nursing E-Logbook.",
  "user": {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "email": "akash.veritos@gmail.com",
    "full_name": "TestSushanVeritos",
    "role": "student"
  }
}
GET /api/coordinator/registration-requests — List Pending Staff Registration Requests
🔒 Auth coordinator +3
API Purpose: Retrieves pending staff registration requests awaiting review by the Year Coordinator or College Admin.

📍 Website Flow Placement

Coordinator Dashboard -> Staff Approvals tab.

🔗 Dependencies & Prerequisites

Requires coordinator assignment.

⚖️ Validation & Business Rules

Scopes results to coordinator's institution and department.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
page query number OPT Pagination page number (default 1).
limit query number OPT Page size (default 20).
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Pending requests returned.
403 Unauthorized role.
Response Payload Structure
Field Type Description
requests[].id string Request identifier.
requests[].email string Applicant email.
requests[].full_name string Applicant name.
requests[].role string Requested role.
requests[].created_at string (ISO Date) Submission date.
Example Success Response (JSON)
{
  "requests": [
    {
      "id": "req-1029-4411",
      "email": "dr.gurpreet@college.edu",
      "full_name": "Dr. Gurpreet Kaur",
      "role": "supervisor",
      "created_at": "2026-09-28T14:20:00.000Z"
    }
  ],
  "total": 1
}
POST /api/coordinator/approve-registration — Approve / Reject Staff Registration Request
🔒 Auth coordinator +3
API Purpose: Approves or rejects a pending staff member registration. On approval, creates the active user record, links college/department, and dispatches welcome credentials.

📍 Website Flow Placement

Coordinator Dashboard -> Staff Approvals -> Approve/Reject action.

🔗 Dependencies & Prerequisites

Requires active registration request record.

⚖️ Validation & Business Rules

Transfers record from `registration_requests` into `users` and `profiles` in a single DB transaction.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
requestId string (UUID) YES Registration request ID to resolve.
action string YES Decision: 'approve' or 'reject'.
departmentId string (UUID) OPT Assigned department on approval.
rejectionReason string OPT Mandatory remarks if rejected.
Example Request Payload (JSON)
{
  "requestId": "req-1029-4411",
  "action": "approve",
  "departmentId": "d-55667788-9900-4112-9988-112233445566"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Registration resolved.
400 Invalid action or missing parameters.
403 Request is outside reviewer's institutional authority.
404 Request ID not found.
Response Payload Structure
Field Type Description
success boolean Resolution outcome.
message string Status notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "Request approved and profile created"
}
POST /api/admin/approve-registration — Admin Approve / Reject Registration Request
🔒 Auth superadmin +1
API Purpose: Superadmin / College Admin override endpoint for resolving pending user registration requests across any college or role.

📍 Website Flow Placement

Superadmin Portal -> User Approvals table.

🔗 Dependencies & Prerequisites

Pending request ID.

⚖️ Validation & Business Rules

Superadmin can approve requests across all colleges; College Admin restricted to own college.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
requestId string (UUID) YES Target request ID.
action string YES 'approve' | 'reject'.
rejectionReason string OPT Reason if rejected.
Example Request Payload (JSON)
{
  "requestId": "req-1029-4411",
  "action": "approve"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Approved/rejected.
403 Non-admin role access denied.
Response Payload Structure
Field Type Description
success boolean Status.
message string Result message.
Example Success Response (JSON)
{
  "success": true,
  "message": "Registration approved successfully."
}

3. Password Management & OTP Recovery

Authenticated self password modification, forgotten password recovery via OTP, and administrative credential resets.

6 APIs
POST /api/auth/change-password — Self Password Change (Authenticated)
🔒 Auth All Authenticated Roles
API Purpose: Allows an authenticated user to change their password by validating their current password and hashing the new one.

📍 Website Flow Placement

User Profile -> Change Password modal, or forced password change interceptor on first login.

🔗 Dependencies & Prerequisites

Requires active session.

⚖️ Validation & Business Rules

Bcrypt hash with cost 12. Sets `force_password_change = 0`. Invalidates previous sessions if configured.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
currentPassword string YES Existing password for confirmation.
newPassword string YES New password (min 8 chars, uppercase, lowercase, digit, symbol).
Example Request Payload (JSON)
{
  "currentPassword": "OldPassword123!",
  "newPassword": "BrandNewSecurePassword2026!"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Password updated successfully.
400 Current password incorrect or new password does not meet security criteria.
401 Session invalid.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Confirmation message.
Example Success Response (JSON)
{
  "success": true,
  "message": "Password changed successfully"
}
POST /api/auth/send-forgot-password-otp — Send Forgot Password OTP
🌐 Public Public
API Purpose: Initiates forgotten password recovery by generating a 6-digit OTP and emailing it to the user if the account exists.

📍 Website Flow Placement

Forgot Password modal on login screen (`/forgot-password`).

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Timing-safe response: always returns 200 generic message to prevent account enumeration.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Account email address.
Example Request Payload (JSON)
{
  "email": "student@example.com"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 OTP sent (or silently ignored if email not found).
429 Too many reset attempts.
Response Payload Structure
Field Type Description
success boolean Always true to prevent email enumeration.
message string Generic instructions message.
Example Success Response (JSON)
{
  "success": true,
  "message": "If an account exists with this email, an OTP code has been sent."
}
POST /api/auth/reset-forgot-password — Reset Password with OTP
🌐 Public Public
API Purpose: Completes the forgotten password reset by verifying the 6-digit OTP and setting the new account password.

📍 Website Flow Placement

Step 2 of the Forgot Password dialog.

🔗 Dependencies & Prerequisites

Requires unexpired OTP issued by `/api/auth/send-forgot-password-otp`.

⚖️ Validation & Business Rules

Constant-time OTP hash check. OTP expires in 15 minutes. Clears `reset_otp` upon completion.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Account email address.
otp string YES 6-digit OTP code received via email.
newPassword string YES New password.
Example Request Payload (JSON)
{
  "email": "student@example.com",
  "otp": "591820",
  "newPassword": "RecoveredPassword2026!"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Password reset complete.
400 Invalid or expired OTP, or weak password.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Confirmation notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "Password reset successfully"
}
POST /api/auth/send-otp-password-change — Send Re-authentication OTP for Password Change
🔒 Auth All Authenticated Roles
API Purpose: Sends a 2-factor OTP verification code to the authenticated user's email prior to changing sensitive security settings.

📍 Website Flow Placement

Triggered when user clicks 'Send Verification Code' in Security Settings.

🔗 Dependencies & Prerequisites

Requires active session.

⚖️ Validation & Business Rules

Email must match authenticated user's email.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES User email address.
Example Request Payload (JSON)
{
  "email": "student@example.com"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 OTP sent.
400 Invalid email.
401 Invalid session.
Response Payload Structure
Field Type Description
success boolean Status.
message string Verification code sent notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "Verification code sent"
}
POST /api/auth/verify-otp-password-change — Verify OTP & Update Password
🔒 Auth All Authenticated Roles
API Purpose: Validates the 2FA OTP code and updates the user's password in high-security workflows.

📍 Website Flow Placement

High-security password change verification step.

🔗 Dependencies & Prerequisites

Requires OTP sent via `/api/auth/send-otp-password-change`.

⚖️ Validation & Business Rules

Validates OTP with constant-time equality.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
otp string YES 6-digit OTP code.
newPassword string YES New password.
Example Request Payload (JSON)
{
  "otp": "712934",
  "newPassword": "NewSecurePassword2026!"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Password updated.
400 Invalid OTP or weak password.
401 Unauthorized.
Response Payload Structure
Field Type Description
success boolean Status.
message string Confirmation.
Example Success Response (JSON)
{
  "success": true,
  "message": "Account updated successfully"
}
PATCH /api/admin/users/:id/password — Admin Force Reset User Password
🔒 Auth superadmin +2
API Purpose: Allows Superadmin, Principal, or College Admin to reset a user's password directly and optionally flag it for mandatory change on next login.

📍 Website Flow Placement

Admin User Management -> Actions -> Reset Password.

🔗 Dependencies & Prerequisites

Target user must exist.

⚖️ Validation & Business Rules

Hashes password with bcrypt cost 12. College Admin cannot reset Superadmin or cross-college user passwords.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Target user ID.
JSON Body Schema
Field Type Required Description
newPassword string YES New password to set for the user.
forceChange boolean OPT Whether user must change it upon next login (default true).
Example Request Payload (JSON)
{
  "newPassword": "TemporaryPass2026!",
  "forceChange": true
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Password reset.
400 Missing or weak password.
403 Target user is outside admin's institutional scope.
404 User ID not found.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status.
Example Success Response (JSON)
{
  "success": true,
  "message": "User password reset successfully."
}

4. Student Portal & Academic Records

Personal profile management, KYC documentation, academic year enrollment, assigned curriculum subjects, logbook entries, and annual appraisal self-ratings.

18 APIs
GET /api/student/info — Get Student Academic & Institutional Profile
🔒 Auth student
API Purpose: Retrieves complete academic status for the authenticated student, including current academic year (Year 1/2/3), course details, college name, and assigned Year Coordinator. Enforces the architecture rule that students belong to an academic year and coordinator, while individual subjects have dedicated teachers.

📍 Website Flow Placement

Primary initialization API invoked when Student logs into the portal (`/student`). Feeds student header bar, profile card, and active course metadata.

🔗 Dependencies & Prerequisites

Requires active record in `student_academic_enrollments`.

⚖️ Validation & Business Rules

Checks active enrollment where `enrollment_status = 'active'`. Returns `coordinator_name` without legacy single supervisor assumptions.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Student academic info returned successfully.
400 No active academic year enrollment found.
401 Unauthorized / session expired.
404 Student profile record not found.
Response Payload Structure
Field Type Description
id string Student profile ID.
student_name string Full name.
roll_number string PNRC Roll / Enrollment number.
course_id string Course ID (e.g. GNM / ANM).
course_name string Course name.
college_id string College institution ID.
college_name string College name.
academic_year_number number Current active academic year (e.g. 1, 2, 3).
coordinator_name string | null Designated Year Coordinator name.
is_promoted boolean True if student has progressed beyond Year 1.
appraisal_status string | null Current annual appraisal status.
Example Success Response (JSON)
{
  "id": "sp-9901-4422",
  "student_name": "Simran Kaur",
  "roll_number": "155854",
  "course_id": "c-gnm-4411-8899-0011",
  "course_name": "General Nursing and Midwifery (GNM)",
  "college_id": "col-1029-4411",
  "college_name": "Government College of Nursing, Patiala",
  "academic_year_number": 1,
  "coordinator_name": "Dr. Jaswinder Kaur",
  "is_promoted": false,
  "appraisal_status": "pending_supervisor_review"
}
GET /api/student/enrollment — Get Student Active Enrollment Record
🔒 Auth student
API Purpose: Returns the detailed academic enrollment row (`student_academic_enrollments`) for the student's active year.

📍 Website Flow Placement

Student Dashboard -> Academic Progress card.

🔗 Dependencies & Prerequisites

Requires active enrollment.

⚖️ Validation & Business Rules

Filters by `student_id = req.user.id AND enrollment_status = 'active'`.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Active enrollment record returned.
401 Unauthorized.
Response Payload Structure
Field Type Description
id string Enrollment record UUID.
student_id string Student user ID.
course_id string Enrolled course.
academic_year_number number Current year number (1, 2, 3).
enrollment_status string Status: 'active', 'completed', 'promoted'.
joining_date string (Date) Academic session start date.
Example Success Response (JSON)
{
  "id": "sae-1029-4411-8899",
  "student_id": "u-94820f12-88aa-4e12-b231-104928adbeef",
  "course_id": "c-gnm-4411-8899-0011",
  "academic_year_number": 1,
  "enrollment_status": "active",
  "joining_date": "2025-08-01"
}
GET /api/student/internship — Get Student Internship / Clinical Posting Alias
🔒 Auth student
API Purpose: Compatibility alias returning the active clinical enrollment and posting details (maps to academic enrollment).

📍 Website Flow Placement

Clinical Logbook and Hospital Posting views.

🔗 Dependencies & Prerequisites

Requires active enrollment.

⚖️ Validation & Business Rules

Resolves hospital affiliation via student college hospital links.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Clinical posting details returned.
401 Unauthorized.
Response Payload Structure
Field Type Description
id string Enrollment ID.
hospital_name string | null Assigned clinical hospital.
current_year number Academic year.
Example Success Response (JSON)
{
  "id": "sae-1029-4411-8899",
  "hospital_name": "Rajindra Hospital, Patiala",
  "current_year": 1
}
GET /api/student/subjects — Get Curriculum Subjects with 1:1 Assigned Teachers
🔒 Auth student
API Purpose: Returns all curriculum subjects configured for the student's active course and academic year, along with the assigned 1:1 dedicated Subject Teacher for each subject.

📍 Website Flow Placement

Student Portal -> Subjects & Teachers tab; Logbook entry creation modal (dropdown for subject selection).

🔗 Dependencies & Prerequisites

Requires active student academic year and subject teacher assignments.

⚖️ Validation & Business Rules

Enforces 1:1 mapping: each subject in an academic year is assigned to a dedicated teacher.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 List of subjects and assigned teachers returned.
401 Unauthorized.
Response Payload Structure
Field Type Description
[].id string Subject master UUID.
[].name string Subject title (e.g. 'Bio-Sciences', 'Nursing Foundations').
[].code string Course subject code.
[].academic_year_number number Academic year this subject belongs to.
[].teacher_id string | null Teacher user ID assigned to evaluate this subject.
[].teacher_name string | null Name of the dedicated subject teacher.
Example Success Response (JSON)
[
  {
    "id": "sub-gnm1-bio",
    "name": "Bio-Sciences (Anatomy & Physiology, Microbiology)",
    "code": "GNM101",
    "academic_year_number": 1,
    "teacher_id": "u-prof-anand-001",
    "teacher_name": "Prof. Anand Sharma"
  },
  {
    "id": "sub-gnm1-found",
    "name": "Fundamentals of Nursing",
    "code": "GNM103",
    "academic_year_number": 1,
    "teacher_id": "u-dr-harpreet-002",
    "teacher_name": "Dr. Harpreet Kaur"
  }
]
GET /api/student/profile-status — Check Student Profile & Verification Status
🔒 Auth student
API Purpose: Returns the KYC verification status (`pending`, `verified`, `rejected`) and flags which mandatory fields or documents (Aadhaar, PAN, PMC) are missing.

📍 Website Flow Placement

Top alert banner on Student Portal notifying student if profile needs completion or verification.

🔗 Dependencies & Prerequisites

Student profile record.

⚖️ Validation & Business Rules

Locked from logbook submissions if status is 'rejected'.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Profile status returned.
401 Unauthorized.
Response Payload Structure
Field Type Description
status string 'pending', 'verified', or 'rejected'.
is_complete boolean Whether all required profile fields are filled.
rejection_remark string | null Reason given by coordinator if rejected.
missing_fields string[] List of missing mandatory profile attributes.
Example Success Response (JSON)
{
  "status": "verified",
  "is_complete": true,
  "rejection_remark": null,
  "missing_fields": []
}
GET /api/student/profile — Get Detailed Student Personal Profile
🔒 Auth student
API Purpose: Retrieves complete personal, demographic, contact, and identity document details for the authenticated student.

📍 Website Flow Placement

Student Portal -> My Profile screen (`/student/profile`).

🔗 Dependencies & Prerequisites

Requires authenticated student.

⚖️ Validation & Business Rules

Aadhaar number masked except for last 4 digits in API response for privacy.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Student profile returned.
404 Profile not found.
Response Payload Structure
Field Type Description
id string Profile UUID.
student_name string Full name.
father_name string Father's name.
mother_name string Mother's name.
date_of_birth string (Date) DOB (YYYY-MM-DD).
gender string Gender.
primary_mobile string Phone number.
email_id string Email address.
permanent_address string Permanent residential address.
correspondence_address string Correspondence address.
photo_url string | null URL to profile photograph.
aadhaar_number string | null Masked Aadhaar number.
pan_number string | null PAN number.
pmc_registration_number string | null Council registration number.
aadhaar_card_url string | null Document URL.
pan_card_url string | null Document URL.
pmc_certificate_url string | null Certificate URL.
Example Success Response (JSON)
{
  "id": "sp-9901-4422",
  "student_name": "Simran Kaur",
  "father_name": "Gurdev Singh",
  "mother_name": "Kulwinder Kaur",
  "date_of_birth": "2004-06-15",
  "gender": "female",
  "primary_mobile": "9876543210",
  "email_id": "simran.kaur@example.com",
  "permanent_address": "VPO Bhadson, Dist. Patiala, Punjab - 147202",
  "correspondence_address": "Room 14, Girls Hostel, GCON Patiala",
  "photo_url": "/uploads/u-94820f12/photo-avatar.jpg",
  "aadhaar_number": "XXXXXXXX1234",
  "pan_number": "ABCDE1234F",
  "pmc_registration_number": "PNRC/GNM/2025/1102"
}
POST /api/student/profile — Update Student Personal Profile
🔒 Auth student
API Purpose: Updates demographic fields, addresses, emergency contacts, and identity documents.

📍 Website Flow Placement

Student Portal -> Edit Profile -> Save Changes.

🔗 Dependencies & Prerequisites

Requires student profile record.

⚖️ Validation & Business Rules

Validates phone formats. Setting KYC values resets `verification_status` to 'pending' for coordinator audit.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
date_of_birth string (YYYY-MM-DD) OPT Date of birth.
gender string OPT Gender: male, female, other.
father_name string OPT Father's name.
mother_name string OPT Mother's name.
permanent_address string OPT Full permanent address.
correspondence_address string OPT Current mailing address.
primary_mobile string OPT 10-digit mobile number.
secondary_mobile string OPT Alternative emergency phone.
aadhaar_number string OPT 12-digit Aadhaar number.
pan_number string OPT 10-character PAN.
pmc_registration_number string OPT State nursing council ID.
photo_url string OPT Uploaded photo file path.
Example Request Payload (JSON)
{
  "father_name": "Gurdev Singh",
  "mother_name": "Kulwinder Kaur",
  "date_of_birth": "2004-06-15",
  "gender": "female",
  "permanent_address": "VPO Bhadson, Dist. Patiala, Punjab - 147202",
  "correspondence_address": "Room 14, Girls Hostel, GCON Patiala",
  "primary_mobile": "9876543210"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Profile saved.
400 Validation error on phone or format.
500 Database error.
Response Payload Structure
Field Type Description
success boolean Update status.
message string Success notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "Profile updated successfully"
}
POST /api/student/upload-photo — Upload Student Profile Photograph
🔒 Auth student
API Purpose: Uploads an official student headshot image (JPEG/PNG), processes thumbnail, and saves photo reference.

📍 Website Flow Placement

Student Profile -> Upload Photo button.

🔗 Dependencies & Prerequisites

Requires authenticated student.

⚖️ Validation & Business Rules

Enforces max 5MB size limit. Replaces previous profile image.

📥 Request Specification

Required Headers
Content-Type: multipart/form-data
JSON Body Schema
Field Type Required Description
file file (binary) YES Image file (JPEG/PNG up to 5MB).
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Photo uploaded and profile updated.
400 No image file provided.
415 Unsupported media type (must be JPEG or PNG).
Response Payload Structure
Field Type Description
success boolean Upload outcome.
photo_url string Resolved photo path.
Example Success Response (JSON)
{
  "success": true,
  "photo_url": "/uploads/u-94820f12/photo-avatar.jpg"
}
GET /api/student/activities — Get Student Activity & Competency Logs
🔒 Auth student
API Purpose: Retrieves activity log entries submitted by the student, filtered by academic year, status (draft, submitted, approved, revision_requested), or competency.

📍 Website Flow Placement

Student Portal -> Clinical Logbook tab.

🔗 Dependencies & Prerequisites

Requires active student profile.

⚖️ Validation & Business Rules

Restricted strictly to records where `student_id = req.user.id`.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
year query number OPT Filter by academic year (e.g. 1, 2, 3).
status query string OPT Filter by submission status ('submitted', 'approved', 'revision_requested').
subject_id query string OPT Filter by specific subject ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Student activities returned.
401 Unauthorized.
Response Payload Structure
Field Type Description
[].id string Activity log UUID.
[].activity_date string (Date) Date procedure was performed.
[].subject_name string Curriculum subject.
[].competency_title string Specific clinical skill or procedure title.
[].status string Evaluation status.
[].supervisor_rating number | null Score given by evaluating teacher (1-5).
[].supervisor_feedback string | null Teacher remarks/critique.
Example Success Response (JSON)
[
  {
    "id": "act-4411-8899",
    "activity_date": "2026-09-20",
    "subject_name": "Fundamentals of Nursing",
    "competency_title": "Intravenous Cannulation & Infusion Setup",
    "status": "approved",
    "supervisor_rating": 5,
    "supervisor_feedback": "Aseptic technique maintained throughout. Good patient rapport."
  }
]
POST /api/student/logbook — Submit Clinical Activity / Logbook Entry
🔒 Auth student
API Purpose: Creates a new clinical activity submission. Automatically identifies the dedicated Subject Teacher for the chosen subject and routes the submission to that teacher's evaluation queue.

📍 Website Flow Placement

Student Portal -> Clinical Logbook -> 'New Entry' modal.

🔗 Dependencies & Prerequisites

Requires active academic enrollment and assigned subject teacher.

⚖️ Validation & Business Rules

Locks submission to the subject's 1:1 assigned teacher. Initial status set to 'submitted'.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
activity_date string (YYYY-MM-DD) YES Date of procedure.
subject_id string (UUID) YES Target subject identifier.
competency_id string (UUID) OPT Competency being demonstrated.
activity_template_id string (UUID) OPT Template form layout ID.
patient_type string OPT Patient type (Adult, Pediatric, Geriatric, Antenatal).
clinical_notes string YES Student's procedural summary and observations.
self_reflection string OPT Student self-reflection on what went well and areas for improvement.
form_data object OPT Dynamic procedure checklist values.
Example Request Payload (JSON)
{
  "activity_date": "2026-09-29",
  "subject_id": "sub-gnm1-found",
  "competency_id": "comp-iv-cannula",
  "patient_type": "Adult",
  "clinical_notes": "Administered 500ml Normal Saline IV via 20G cannula in left cephalic vein under aseptic precautions.",
  "self_reflection": "Found vein on first attempt; need to improve tape fixation speed."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Activity submitted successfully.
400 No active enrollment or missing required clinical notes.
404 Subject not found.
Response Payload Structure
Field Type Description
success boolean Submission outcome.
id string Created activity record ID.
assigned_teacher string Teacher who will evaluate this entry.
Example Success Response (JSON)
{
  "success": true,
  "id": "act-4411-8899",
  "assigned_teacher": "Dr. Harpreet Kaur"
}
PATCH /api/student/logbook/:id — Update Draft / Revise Logbook Entry
🔒 Auth student
API Purpose: Allows a student to modify an existing logbook entry while in 'draft' or 'revision_requested' status.

📍 Website Flow Placement

Student Portal -> Logbook -> 'Edit' or 'Resubmit' button.

🔗 Dependencies & Prerequisites

Existing logbook entry owned by student.

⚖️ Validation & Business Rules

Approved entries cannot be edited. Resubmission resets review status to pending.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Activity log ID.
JSON Body Schema
Field Type Required Description
clinical_notes string OPT Updated notes.
self_reflection string OPT Updated reflection.
status string OPT 'draft' or 'resubmitted'.
Example Request Payload (JSON)
{
  "clinical_notes": "Updated documentation addressing teacher feedback on cannulation site care.",
  "status": "resubmitted"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Logbook entry updated.
400 No fields provided to update.
404 Record not found or not owned by student.
409 Entry is locked (already approved or cancelled).
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/student/activity-types — Get Available Activity Types for Student Department
🔒 Auth student
API Purpose: Lists the activity classifications (e.g. Clinical Ward, OT, Community Health, Midwifery) available for the student's department.

📍 Website Flow Placement

Logbook Entry Creation dropdown.

🔗 Dependencies & Prerequisites

Department ID in student profile.

⚖️ Validation & Business Rules

Filters to active types belonging to student's department.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Activity types returned.
Response Payload Structure
Field Type Description
[].id string Activity type ID.
[].name string Type title.
[].description string Clinical scope.
Example Success Response (JSON)
[
  {
    "id": "at-clinical-ward",
    "name": "Clinical Ward Procedure",
    "description": "Routine inpatient nursing procedures and vital monitoring."
  }
]
GET /api/student/appraisal-forms — Get Applicable Annual Appraisal Templates
🔒 Auth student
API Purpose: Returns the annual appraisal form template configured for the student's course and active academic year.

📍 Website Flow Placement

Student Portal -> Annual Appraisal tab.

🔗 Dependencies & Prerequisites

Requires active academic enrollment.

⚖️ Validation & Business Rules

Returns templates where `course_id` and `academic_year_number` match student's active enrollment.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Appraisal templates returned.
Response Payload Structure
Field Type Description
[].id string Template UUID.
[].title string Appraisal template title (e.g. GNM 1st Year Annual Appraisal).
[].year_number number Academic year.
Example Success Response (JSON)
[
  {
    "id": "tmpl-gnm-yr1",
    "title": "GNM 1st Year Annual Appraisal & Competency Assessment",
    "year_number": 1
  }
]
GET /api/student/appraisal-forms/:id — Get Appraisal Form Schema & Rubric Questions
🔒 Auth student
API Purpose: Retrieves the full form structure, rating scales, and evaluation questions for a specific appraisal template.

📍 Website Flow Placement

Student Appraisal viewer modal.

🔗 Dependencies & Prerequisites

Template ID.

⚖️ Validation & Business Rules

Combines template headers with child question rows.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Template form ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Form structure returned.
404 Form not found.
Response Payload Structure
Field Type Description
id string Form ID.
title string Form title.
questions[].id string Question ID.
questions[].section string Domain section.
questions[].question_text string Evaluation criterion.
Example Success Response (JSON)
{
  "id": "tmpl-gnm-yr1",
  "title": "GNM 1st Year Annual Appraisal",
  "questions": [
    {
      "id": "q-prof-conduct",
      "section": "Professional Demeanor",
      "question_text": "Demonstrates punctuality, uniform adherence, and clinical ethics."
    }
  ]
}
GET /api/student/appraisal-forms/:id/fields — Get Appraisal Dynamic Fields
🔒 Auth student
API Purpose: Retrieves dynamic fields and custom input criteria for a specific appraisal form.

📍 Website Flow Placement

Appraisal form dynamic renderer.

🔗 Dependencies & Prerequisites

Form ID.

⚖️ Validation & Business Rules

Sorted by field display order.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Form ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Fields returned.
Response Payload Structure
Field Type Description
[].field_key string Key name.
[].label string Display label.
[].field_type string Input type (rating, text, number).
Example Success Response (JSON)
[
  {
    "field_key": "attendance_percentage",
    "label": "Total Clinical Attendance (%)",
    "field_type": "number"
  }
]
GET /api/student/appraisals — List Student Annual Appraisals
🔒 Auth student
API Purpose: Retrieves all annual appraisals submitted for the student across their academic tenure, showing status (draft, supervisor_evaluated, hod_verified, principal_approved).

📍 Website Flow Placement

Student Portal -> Appraisal Records tab.

🔗 Dependencies & Prerequisites

Requires student identity.

⚖️ Validation & Business Rules

Read-only history view.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Appraisal history returned.
Response Payload Structure
Field Type Description
[].id string Appraisal submission ID.
[].year_number number Academic year evaluated.
[].status string Appraisal workflow state.
[].supervisor_rating number | null Overall supervisor score.
[].principal_approved_at string | null Final approval date.
Example Success Response (JSON)
[
  {
    "id": "appr-2025-01",
    "year_number": 1,
    "status": "principal_approved",
    "supervisor_rating": 4.8,
    "principal_approved_at": "2026-09-15T11:00:00.000Z"
  }
]
PATCH /api/student/appraisals/:id/sign — Digital Sign-off on Completed Appraisal
🔒 Auth student
API Purpose: Allows the student to review their final annual appraisal marks and submit their digital acknowledgement signature.

📍 Website Flow Placement

Student Portal -> Appraisal Details -> 'Acknowledge & Sign' button.

🔗 Dependencies & Prerequisites

Appraisal must be approved by Principal.

⚖️ Validation & Business Rules

Sets `student_signed_at = NOW()` and locks record against further modifications.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Appraisal record ID.
JSON Body Schema
Field Type Required Description
student_comments string OPT Optional student remarks.
Example Request Payload (JSON)
{
  "student_comments": "I have reviewed my annual evaluation scores and feedback."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Sign-off recorded.
404 Appraisal not found.
Response Payload Structure
Field Type Description
success boolean Sign-off outcome.
message string Confirmation notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "Appraisal signed successfully"
}
GET /api/student/payments — Get Student Fee & Payment History
🔒 Auth student
API Purpose: Returns fee receipts and transactions associated with the student's enrollment.

📍 Website Flow Placement

Student Portal -> Fees & Transactions tab.

🔗 Dependencies & Prerequisites

Student profile.

⚖️ Validation & Business Rules

Returns null if fee tracking is disabled or institutional direct-billing applies.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Payment records returned.
Returns empty body (e.g. 204 No Content).

5. Supervisor & Subject Teacher Portal

Subject teacher evaluation workflows, student logbook review queues, competency verification, and annual appraisal scoring.

9 APIs
GET /api/supervisor/students — List Supervised Students in Assigned Subjects
🔒 Auth supervisor +4
API Purpose: Retrieves students enrolled in academic years where the authenticated teacher has assigned subjects. Teachers evaluate only students within their designated college, course, and year.

📍 Website Flow Placement

Supervisor Dashboard -> 'My Students' roster.

🔗 Dependencies & Prerequisites

Requires active record in `subject_teacher_assignments`.

⚖️ Validation & Business Rules

Scopes students strictly to courses and academic years where the supervisor has an active subject assignment.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
academic_year query number OPT Filter by academic year number.
course_id query string OPT Filter by course.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Student cohort returned.
401 Unauthorized.
Response Payload Structure
Field Type Description
[].id string Student user ID.
[].student_name string Student full name.
[].roll_number string Roll number.
[].course_name string Enrolled course.
[].academic_year_number number Year of study.
[].assigned_subjects string[] Subject(s) taught by this supervisor.
Example Success Response (JSON)
[
  {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "student_name": "Simran Kaur",
    "roll_number": "155854",
    "course_name": "GNM",
    "academic_year_number": 1,
    "assigned_subjects": [
      "Fundamentals of Nursing"
    ]
  }
]
GET /api/supervisor/student-stats/:studentId — Get Student Activity Statistics
🔒 Auth supervisor +4
API Purpose: Calculates total submissions, approved count, pending review count, and revision requested count for a specific student.

📍 Website Flow Placement

Supervisor Student Detail Drawer.

🔗 Dependencies & Prerequisites

Supervisor-student relationship.

⚖️ Validation & Business Rules

Restricted to authorized teachers of the student.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
studentId path string YES Target student user ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Statistics calculated.
403 Unauthorized access (student not in supervisor's cohort).
Response Payload Structure
Field Type Description
total_activities number Total logbook submissions.
approved number Approved submissions.
pending number Submissions awaiting evaluation.
revision_requested number Submissions sent back for correction.
average_rating number Mean competency rating (out of 5.0).
Example Success Response (JSON)
{
  "total_activities": 42,
  "approved": 38,
  "pending": 3,
  "revision_requested": 1,
  "average_rating": 4.6
}
GET /api/supervisor/activities — List Activity Submissions for Review
🔒 Auth supervisor +4
API Purpose: Retrieves student logbook submissions awaiting review, filtered strictly to subjects assigned to the authenticated teacher.

📍 Website Flow Placement

Supervisor Dashboard -> 'Submissions Review Queue'.

🔗 Dependencies & Prerequisites

Assigned subjects.

⚖️ Validation & Business Rules

Only displays activities belonging to subjects the teacher is authorized to evaluate.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
status query string OPT Filter: 'submitted', 'resubmitted', 'approved', 'rejected'.
student_id query string OPT Filter by student.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Submissions list returned.
Response Payload Structure
Field Type Description
[].id string Activity ID.
[].student_name string Student name.
[].subject_name string Subject title.
[].activity_date string Procedure date.
[].clinical_notes string Procedure notes.
[].status string Current status.
Example Success Response (JSON)
[
  {
    "id": "act-4411-8899",
    "student_name": "Simran Kaur",
    "subject_name": "Fundamentals of Nursing",
    "activity_date": "2026-09-29",
    "clinical_notes": "Administered 500ml Normal Saline IV via 20G cannula.",
    "status": "submitted"
  }
]
PATCH /api/supervisor/activities/:id/review — Evaluate & Review Student Activity Submission
🔒 Auth supervisor +4
API Purpose: Submits teacher evaluation, clinical score (1-5), and feedback remarks for an activity submission.

📍 Website Flow Placement

Supervisor Review Queue -> Evaluate Modal -> Submit Review.

🔗 Dependencies & Prerequisites

Submission must belong to a subject assigned to this teacher.

⚖️ Validation & Business Rules

Strict authorization: verifies teacher assignment in `subject_teacher_assignments`.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Activity submission ID.
JSON Body Schema
Field Type Required Description
status string YES 'approved', 'rejected', or 'revision_requested'.
supervisor_rating number YES Integer competency rating between 1 and 5.
supervisor_feedback string OPT Constructive feedback and guidance.
Example Request Payload (JSON)
{
  "status": "approved",
  "supervisor_rating": 5,
  "supervisor_feedback": "Demonstrated excellent aseptic technique. Log approved."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Review saved.
400 Rating must be 1-5 or invalid status.
404 Submission not found or teacher unauthorized for this subject.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Confirmation notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "Activity submission marked as approved"
}
GET /api/supervisor/profiles — List Student Profiles for Verification
🔒 Auth supervisor +3
API Purpose: Returns student profiles in supervisor's cohort awaiting KYC verification.

📍 Website Flow Placement

Profile Verification tab.

🔗 Dependencies & Prerequisites

Cohort assignment.

⚖️ Validation & Business Rules

Restricted to assigned students.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Profiles returned.
Response Payload Structure
Field Type Description
[].id string Profile ID.
[].student_name string Student name.
[].verification_status string Verification state.
Example Success Response (JSON)
[
  {
    "id": "sp-9901-4422",
    "student_name": "Simran Kaur",
    "verification_status": "pending"
  }
]
PATCH /api/supervisor/profiles/:id/verify — Verify or Reject Student Profile
🔒 Auth supervisor +3
API Purpose: Validates or rejects student demographic information and identity documents.

📍 Website Flow Placement

Profile Verification screen.

🔗 Dependencies & Prerequisites

Profile record.

⚖️ Validation & Business Rules

Sets `verified_at` and `verified_by` audit fields.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Student profile ID.
JSON Body Schema
Field Type Required Description
status string YES 'verified' | 'rejected'.
rejection_remark string OPT Reason if rejected.
Example Request Payload (JSON)
{
  "status": "verified"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Profile verification updated.
403 Unauthorized to verify this student.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/supervisor/appraisals — List Pending Student Annual Appraisals
🔒 Auth supervisor +4
API Purpose: Retrieves student annual appraisals awaiting supervisor evaluation in the teacher's cohort.

📍 Website Flow Placement

Supervisor Dashboard -> Annual Appraisals tab.

🔗 Dependencies & Prerequisites

Appraisal cycle active.

⚖️ Validation & Business Rules

Scoped to teacher's academic cohort.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Appraisals queue returned.
Response Payload Structure
Field Type Description
[].id string Appraisal ID.
[].student_name string Student name.
[].year_number number Academic year.
[].status string Workflow state.
Example Success Response (JSON)
[
  {
    "id": "appr-2026-9901",
    "student_name": "Simran Kaur",
    "year_number": 1,
    "status": "pending_supervisor_review"
  }
]
GET /api/supervisor/student-appraisals — Get Student Appraisal History Roster
🔒 Auth supervisor +4
API Purpose: Returns historical appraisal records for students in supervisor's cohort.

📍 Website Flow Placement

Appraisal Archive view.

🔗 Dependencies & Prerequisites

Cohort linkage.

⚖️ Validation & Business Rules

Read-only access.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Roster returned.
Example Success Response (JSON)
[]
GET /api/supervisor/appraisals/submissions/detailed — Get Detailed Appraisal Submission with Responses
🔒 Auth supervisor +4
API Purpose: Retrieves complete appraisal form data including section-by-section answers, rubric scores, and remarks.

📍 Website Flow Placement

Supervisor Appraisal Scoring sheet.

🔗 Dependencies & Prerequisites

Appraisal submission.

⚖️ Validation & Business Rules

Teacher must supervise student's cohort.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id query string YES Appraisal or enrollment ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Detailed appraisal returned.
404 Appraisal not found.
Response Payload Structure
Field Type Description
id string Appraisal ID.
student_name string Student name.
responses array Detailed response questions and marks.
Example Success Response (JSON)
{
  "id": "appr-2026-9901",
  "student_name": "Simran Kaur",
  "responses": [
    {
      "question_id": "q-prof-conduct",
      "rating": 5,
      "remarks": "Exemplary attitude and attendance."
    }
  ]
}

6. Year Coordinator Portal

Academic year cohort oversight, performance aggregation across all subjects, and intermediate review of annual appraisals.

4 APIs
GET /api/coordinator/performance-stats — Get Year Cohort Performance & Aggregates
🔒 Auth coordinator +3
API Purpose: Aggregates academic and clinical performance statistics across all subjects for students in the coordinator's assigned academic year.

📍 Website Flow Placement

Coordinator Dashboard overview.

🔗 Dependencies & Prerequisites

Requires coordinator assignment in `year_coordinator_assignments`.

⚖️ Validation & Business Rules

Scoped to coordinator's institution, course, and year.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Aggregates calculated.
Response Payload Structure
Field Type Description
[].course_name string Course.
[].total_students number Enrolled students.
[].average_completion number Percentage of competencies completed.
Example Success Response (JSON)
[
  {
    "course_name": "GNM 1st Year",
    "total_students": 45,
    "average_completion": 82.5
  }
]
GET /api/coordinator/appraisals — List Appraisals Pending Coordinator Review
🔒 Auth coordinator +3
API Purpose: Lists student annual appraisals that have been evaluated by Subject Teachers/Supervisors and now require Year Coordinator endorsement.

📍 Website Flow Placement

Coordinator Dashboard -> Annual Review tab.

🔗 Dependencies & Prerequisites

Teacher evaluation completed.

⚖️ Validation & Business Rules

Displays records where `status = 'supervisor_evaluated'`.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Appraisals queue returned.
Response Payload Structure
Field Type Description
[].id string Appraisal ID.
[].student_name string Student name.
[].supervisor_rating number Score given by teacher.
Example Success Response (JSON)
[
  {
    "id": "appr-2026-9901",
    "student_name": "Simran Kaur",
    "supervisor_rating": 4.8
  }
]
PATCH /api/coordinator/appraisals/:id/review — Submit Coordinator Review on Appraisal
🔒 Auth coordinator +3
API Purpose: Records coordinator endorsement remarks and forwards appraisal to Principal for final sign-off.

📍 Website Flow Placement

Coordinator Appraisal Review Sheet.

🔗 Dependencies & Prerequisites

Appraisal in reviewable state.

⚖️ Validation & Business Rules

Moves status to `hod_verified` / `coordinator_approved`.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Appraisal ID.
JSON Body Schema
Field Type Required Description
status string YES 'coordinator_approved' or 'revision_requested'.
remarks string OPT Coordinator comments.
Example Request Payload (JSON)
{
  "status": "coordinator_approved",
  "remarks": "All 1st year clinical mandates and classroom requirements fulfilled."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Review recorded.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/coordinator/appraisals/submissions/detailed — Get Coordinator Detailed Appraisal View
🔒 Auth coordinator +3
API Purpose: Retrieves complete evaluation submission for coordinator inspection.

📍 Website Flow Placement

Coordinator Detailed Appraisal Inspection modal.

🔗 Dependencies & Prerequisites

Appraisal ID.

⚖️ Validation & Business Rules

Restricted to coordinator's cohort.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id query string YES Submission ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Details returned.
Example Success Response (JSON)
{}

7. Principal & Institutional Administration

College-wide institutional governance, comprehensive analytics, leave resolutions, and final annual appraisal sign-offs.

12 APIs
GET /api/principal/stats — Get College-Wide Executive Metrics
🔒 Auth principal +1
API Purpose: Returns high-level institution metrics: total student enrollment, total faculty count, pending activity submissions, pending leave requests, and pending appraisal sign-offs.

📍 Website Flow Placement

Principal Dashboard landing view (`/principal`).

🔗 Dependencies & Prerequisites

Principal role.

⚖️ Validation & Business Rules

Scoped strictly to `req.user.college_id`.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 College metrics returned.
403 Access denied (Principal role only).
Response Payload Structure
Field Type Description
totalStudents number Total enrolled students in college.
totalFaculty number Total faculty members.
pendingActivities number Activities awaiting faculty action.
pendingLeaves number Leave requests awaiting resolution.
pendingAppraisals number Appraisals awaiting principal approval.
Example Success Response (JSON)
{
  "totalStudents": 180,
  "totalFaculty": 18,
  "pendingActivities": 14,
  "pendingLeaves": 3,
  "pendingAppraisals": 12
}
GET /api/principal/analytics — Get College Analytics & Departmental Breakdown
🔒 Auth principal +1
API Purpose: Retrieves distribution of students, compliance rates, and attendance statistics grouped by department and academic year.

📍 Website Flow Placement

Principal Dashboard -> Analytics tab.

🔗 Dependencies & Prerequisites

Principal role.

⚖️ Validation & Business Rules

Institutional scope enforced.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Analytics returned.
Response Payload Structure
Field Type Description
departmentBreakdown array Enrollment by department.
activityTrends array Submission velocity trends.
Example Success Response (JSON)
{
  "departmentBreakdown": [
    {
      "department_name": "GNM",
      "count": 120
    },
    {
      "department_name": "ANM",
      "count": 60
    }
  ],
  "activityTrends": [
    {
      "week": "W38",
      "approved": 140,
      "submitted": 155
    }
  ]
}
GET /api/principal/departments — List College Academic Departments
🔒 Auth principal +1
API Purpose: Lists all departments belonging to the Principal's college.

📍 Website Flow Placement

Principal college management tabs.

🔗 Dependencies & Prerequisites

College ID.

⚖️ Validation & Business Rules

Scoped to college.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Departments returned.
Response Payload Structure
Field Type Description
[].id string Department ID.
[].name string Department name.
Example Success Response (JSON)
[
  {
    "id": "dept-gnm-01",
    "name": "General Nursing & Midwifery"
  },
  {
    "id": "dept-anm-01",
    "name": "Auxiliary Nurse Midwifery"
  }
]
GET /api/principal/hods — List Course Coordinators & HODs
🔒 Auth principal +1
API Purpose: Retrieves all Course Coordinators and HODs active in the college.

📍 Website Flow Placement

Principal Staff Directory.

🔗 Dependencies & Prerequisites

College linkage.

⚖️ Validation & Business Rules

College scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Coordinators returned.
Response Payload Structure
Field Type Description
[].id string Staff user ID.
[].full_name string Name.
[].role string Role.
Example Success Response (JSON)
[
  {
    "id": "u-coord-01",
    "full_name": "Dr. Jaswinder Kaur",
    "role": "coordinator"
  }
]
GET /api/principal/supervisors — List College Subject Teachers / Supervisors
🔒 Auth principal +1
API Purpose: Retrieves all Subject Teachers and Clinical Supervisors employed at the college.

📍 Website Flow Placement

Principal Faculty Management view.

🔗 Dependencies & Prerequisites

College linkage.

⚖️ Validation & Business Rules

College scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Supervisors list returned.
Response Payload Structure
Field Type Description
[].id string Teacher user ID.
[].full_name string Teacher name.
Example Success Response (JSON)
[
  {
    "id": "u-prof-anand-001",
    "full_name": "Prof. Anand Sharma"
  }
]
GET /api/principal/students — List All Enrolled Students in College
🔒 Auth principal +1
API Purpose: Returns all students enrolled across all courses and academic years in the Principal's institution.

📍 Website Flow Placement

Principal Student Directory (`/principal/students`).

🔗 Dependencies & Prerequisites

College linkage.

⚖️ Validation & Business Rules

Restricted to principal's college.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
year query number OPT Filter by academic year.
search query string OPT Search by student name or roll number.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Students list returned.
Response Payload Structure
Field Type Description
[].id string Student ID.
[].full_name string Student name.
[].roll_number string Roll number.
[].course_name string Course.
[].academic_year_number number Year of study.
Example Success Response (JSON)
[
  {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "full_name": "Simran Kaur",
    "roll_number": "155854",
    "course_name": "GNM",
    "academic_year_number": 1
  }
]
GET /api/principal/search — Universal College Entity Search
🔒 Auth principal +1
API Purpose: Searches students, faculty, coordinators, and departments matching a query string across the institution.

📍 Website Flow Placement

Top search bar on Principal Portal.

🔗 Dependencies & Prerequisites

College linkage.

⚖️ Validation & Business Rules

Minimum 2 characters.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
q query string YES Search keyword.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Search results returned.
Response Payload Structure
Field Type Description
[].id string Entity ID.
[].title string Display label.
[].type string 'student', 'faculty', 'department'.
Example Success Response (JSON)
[
  {
    "id": "u-94820f12",
    "title": "Simran Kaur (155854)",
    "type": "student"
  }
]
GET /api/principal/activities — List College Activities for Escalation / Audit
🔒 Auth principal +1
API Purpose: Allows the Principal to view all activity submissions in the college, including flagged or contested reviews.

📍 Website Flow Placement

Principal Clinical Audit tab.

🔗 Dependencies & Prerequisites

College linkage.

⚖️ Validation & Business Rules

College scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Activities returned.
Example Success Response (JSON)
[]
POST /api/principal/activities/:id/resolve — Resolve Contested Activity Submission
🔒 Auth principal +1
API Purpose: Enables the Principal to override or resolve contested activity reviews as executive authority.

📍 Website Flow Placement

Principal Contested Submissions view.

🔗 Dependencies & Prerequisites

Activity record.

⚖️ Validation & Business Rules

Logs executive resolution audit.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Activity ID.
JSON Body Schema
Field Type Required Description
action string YES 'approve' | 'reject'.
remarks string YES Resolution rationale.
Example Request Payload (JSON)
{
  "action": "approve",
  "remarks": "Verified with Clinical Instructor; procedure meets criteria."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Activity resolved.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status.
Example Success Response (JSON)
{
  "success": true,
  "message": "Activity approved successfully"
}
GET /api/principal/leaves — List College Leave Requests
🔒 Auth principal +1
API Purpose: Retrieves student and staff leave requests requiring executive approval.

📍 Website Flow Placement

Principal Leaves Management panel.

🔗 Dependencies & Prerequisites

College linkage.

⚖️ Validation & Business Rules

Scoped to college.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Leave requests returned.
Response Payload Structure
Field Type Description
[].id string Leave request ID.
[].applicant_name string Applicant.
[].reason string Leave reason.
[].start_date string Start date.
[].end_date string End date.
Example Success Response (JSON)
[
  {
    "id": "l-4411-8899",
    "applicant_name": "Simran Kaur",
    "reason": "Medical Leave (Fever)",
    "start_date": "2026-09-25",
    "end_date": "2026-09-27"
  }
]
POST /api/principal/leaves/:id/resolve — Approve or Reject Leave Request
🔒 Auth principal +1
API Purpose: Executes final executive approval or rejection of student and staff leave applications.

📍 Website Flow Placement

Principal Leave Approval modal.

🔗 Dependencies & Prerequisites

Leave application.

⚖️ Validation & Business Rules

Notifies student/staff of approval.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Leave ID.
JSON Body Schema
Field Type Required Description
action string YES 'approve' | 'reject'.
remarks string OPT Remarks.
Example Request Payload (JSON)
{
  "action": "approve",
  "remarks": "Approved as per medical certificate."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Leave resolved.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status.
Example Success Response (JSON)
{
  "success": true,
  "message": "Leave approved successfully"
}
GET /api/principal/appraisals — List Appraisals Pending Final Principal Sign-off
🔒 Auth principal +1
API Purpose: Retrieves student annual appraisals endorsed by the Year Coordinator, awaiting final Principal sign-off required for academic promotion.

📍 Website Flow Placement

Principal Dashboard -> Annual Appraisal Sign-offs.

🔗 Dependencies & Prerequisites

Coordinator endorsement completed.

⚖️ Validation & Business Rules

Approval unlocks student eligibility for Year Promotion (`POST /api/promotion/promote`).

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Appraisals list returned.
Response Payload Structure
Field Type Description
[].id string Appraisal ID.
[].student_name string Student name.
[].year_number number Academic year.
[].status string Workflow state.
Example Success Response (JSON)
[
  {
    "id": "appr-2026-9901",
    "student_name": "Simran Kaur",
    "year_number": 1,
    "status": "coordinator_approved"
  }
]

8. Subject & Coordinator Assignments

Institutional governance enforcing 1:1 dedicated teacher assignments per subject in each academic year, and designated Year Coordinator assignments per cohort.

7 APIs
GET /api/subject-assignments/my-subjects — Get Assigned Subjects for Authenticated Teacher
🔒 Auth supervisor +4
API Purpose: Returns all active subjects assigned to the logged-in teacher across courses and academic years in their college. Enforces the rule that teachers only evaluate activities and students for their assigned subjects.

📍 Website Flow Placement

Invoked on Supervisor Dashboard load to filter submission queues, competencies, and student rosters.

🔗 Dependencies & Prerequisites

Requires active assignment in `subject_teacher_assignments` table.

⚖️ Validation & Business Rules

Filters by `teacher_id = req.user.id AND is_active = 1`.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Assigned subjects list returned.
500 Failed to fetch assigned subjects.
Response Payload Structure
Field Type Description
success boolean Query success flag.
subjects[].id string Assignment ID.
subjects[].subject_id string Curriculum subject ID.
subjects[].subject_name string Subject title.
subjects[].subject_code string Subject code.
subjects[].course_id string Course ID.
subjects[].course_name string Course name.
subjects[].academic_year_number number Academic year (1, 2, 3).
Example Success Response (JSON)
{
  "success": true,
  "subjects": [
    {
      "id": "sta-4411-8899",
      "subject_id": "sub-gnm1-found",
      "subject_name": "Fundamentals of Nursing",
      "subject_code": "GNM103",
      "course_id": "c-gnm-4411-8899-0011",
      "course_name": "General Nursing and Midwifery (GNM)",
      "academic_year_number": 1
    }
  ]
}
GET /api/subject-assignments — List All Subject Teacher Assignments
🔒 Auth superadmin +4
API Purpose: Retrieves all subject teacher assignments for a college, course, and academic year. Allows administrators to verify that each subject has a dedicated 1:1 teacher assigned.

📍 Website Flow Placement

College Admin / Principal / Coordinator -> Subject Assignments management page.

🔗 Dependencies & Prerequisites

Requires subjects and teachers registered in the college.

⚖️ Validation & Business Rules

Non-superadmins are restricted to viewing assignments for their own `college_id`.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
college_id query string OPT College filter (mandatory for superadmin if not specified).
course_id query string OPT Filter by course.
academic_year_number query number OPT Filter by academic year (1, 2, 3).
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Assignments returned.
403 Unauthorized access.
Response Payload Structure
Field Type Description
success boolean Outcome.
data[].id string Assignment ID.
data[].teacher_id string Teacher ID.
data[].teacher_name string Teacher name.
data[].subject_id string Subject ID.
data[].subject_name string Subject title.
data[].course_name string Course name.
data[].academic_year_number number Year.
Example Success Response (JSON)
{
  "success": true,
  "data": [
    {
      "id": "sta-4411-8899",
      "teacher_id": "u-prof-anand-001",
      "teacher_name": "Prof. Anand Sharma",
      "subject_id": "sub-gnm1-bio",
      "subject_name": "Bio-Sciences (Anatomy & Physiology, Microbiology)",
      "course_name": "General Nursing and Midwifery (GNM)",
      "academic_year_number": 1
    }
  ]
}
POST /api/subject-assignments — Assign Dedicated 1:1 Subject Teacher
🔒 Auth superadmin +3
API Purpose: Assigns a faculty teacher to a specific curriculum subject in an academic year. Strictly enforces the 1:1 constraint: a subject in an academic year can only have one active teacher, and a teacher can only be assigned to one subject per academic year.

📍 Website Flow Placement

Coordinator / Principal -> Subject Assignment -> 'Assign Teacher' modal.

🔗 Dependencies & Prerequisites

Requires subject in `subjects` table and teacher profile in `profiles` table.

⚖️ Validation & Business Rules

Architecture Constraint: Strictly 1:1 teacher per subject. Enforced via database unique check and service level validation.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
teacher_id string (UUID) YES Faculty user ID to assign.
subject_id string (UUID) YES Curriculum subject ID.
course_id string (UUID) YES Course ID.
academic_year_number number YES Academic year (1, 2, 3).
college_id string (UUID) OPT College ID (required for superadmin).
Example Request Payload (JSON)
{
  "teacher_id": "u-dr-harpreet-002",
  "subject_id": "sub-gnm1-found",
  "course_id": "c-gnm-4411-8899-0011",
  "academic_year_number": 1,
  "college_id": "col-1029-4411"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Teacher assigned successfully.
400 Subject already assigned to another teacher, or teacher already assigned to another subject in this year.
403 Teacher belongs to a different college.
404 Teacher or Subject not found.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status message.
assignment_id string Newly created assignment ID.
Example Success Response (JSON)
{
  "success": true,
  "message": "Subject teacher assigned successfully",
  "assignment_id": "sta-4411-8899-0012"
}
DELETE /api/subject-assignments/:id — Deactivate Subject Teacher Assignment
🔒 Auth superadmin +3
API Purpose: Deactivates an active subject-teacher assignment so another teacher can be assigned to the subject.

📍 Website Flow Placement

Subject Assignments table -> 'Remove Assignment' button.

🔗 Dependencies & Prerequisites

Existing assignment record.

⚖️ Validation & Business Rules

Soft-deletes by setting `is_active = 0`.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Assignment ID to deactivate.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Assignment deactivated.
404 Assignment not found or unauthorized.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status.
Example Success Response (JSON)
{
  "success": true,
  "message": "Assignment deactivated"
}
GET /api/coordinator-assignments — List Year Coordinator Assignments
🔒 Auth superadmin +4
API Purpose: Retrieves active Year Coordinator assignments across courses and academic years.

📍 Website Flow Placement

Principal Dashboard -> Coordinator Assignments tab.

🔗 Dependencies & Prerequisites

College linkage.

⚖️ Validation & Business Rules

Restricted to user's college scope.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
college_id query string OPT Filter by college ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Coordinators list returned.
Response Payload Structure
Field Type Description
success boolean Outcome.
data[].id string Assignment ID.
data[].coordinator_name string Coordinator name.
data[].course_name string Course title.
data[].academic_year_number number Year of study.
Example Success Response (JSON)
{
  "success": true,
  "data": [
    {
      "id": "yca-1029-4411",
      "coordinator_name": "Dr. Jaswinder Kaur",
      "course_name": "General Nursing and Midwifery (GNM)",
      "academic_year_number": 1
    }
  ]
}
POST /api/coordinator-assignments — Assign Year Coordinator
🔒 Auth superadmin +2
API Purpose: Assigns a designated faculty member as the Year Coordinator for an academic year cohort (e.g. GNM Year 1 Coordinator).

📍 Website Flow Placement

Principal Portal -> 'Assign Year Coordinator' modal.

🔗 Dependencies & Prerequisites

Requires coordinator profile.

⚖️ Validation & Business Rules

Inserts record into `year_coordinator_assignments` with `is_active = 1`.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
coordinator_id string (UUID) YES Coordinator user ID.
course_id string (UUID) YES Course ID.
academic_year_number number YES Academic year (1, 2, 3).
college_id string (UUID) OPT College ID.
Example Request Payload (JSON)
{
  "coordinator_id": "u-coord-01",
  "course_id": "c-gnm-4411-8899-0011",
  "academic_year_number": 1,
  "college_id": "col-1029-4411"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Coordinator assigned.
400 Missing fields or invalid course.
403 Coordinator belongs to a different college.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status message.
assignment_id string Assignment ID.
Example Success Response (JSON)
{
  "success": true,
  "message": "Coordinator assigned to year successfully",
  "assignment_id": "yca-1029-4411"
}
DELETE /api/coordinator-assignments/:id — Deactivate Year Coordinator Assignment
🔒 Auth superadmin +2
API Purpose: Deactivates an active coordinator assignment.

📍 Website Flow Placement

Coordinator Assignments table -> 'Remove' action.

🔗 Dependencies & Prerequisites

Assignment record.

⚖️ Validation & Business Rules

Soft-deletes record (`is_active = 0`).

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Assignment ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deactivated.
404 Not found.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status.
Example Success Response (JSON)
{
  "success": true,
  "message": "Coordinator assignment deactivated"
}

9. Annual Appraisal & Academic Promotion Workflow

Multi-tier annual competency appraisals (Supervisor Evaluation -> Coordinator Endorsement -> Principal Approval) and academic progression promotion from Year N to Year N+1.

11 APIs
GET /api/appraisal/eligible-students — List Students Eligible for Annual Appraisal
🔒 Auth supervisor +1
API Purpose: Returns students in the supervisor's cohort who have completed required clinical activities and are ready for annual competency evaluation.

📍 Website Flow Placement

Supervisor Portal -> Annual Appraisal Assessment tab.

🔗 Dependencies & Prerequisites

Active cohort students.

⚖️ Validation & Business Rules

Filters students in active enrollment.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Eligible students returned.
Response Payload Structure
Field Type Description
[].id string Student ID.
[].student_name string Student name.
[].academic_year_number number Current year.
[].completed_logs number Total approved logbook entries.
Example Success Response (JSON)
[
  {
    "id": "u-94820f12-88aa-4e12-b231-104928adbeef",
    "student_name": "Simran Kaur",
    "academic_year_number": 1,
    "completed_logs": 45
  }
]
GET /api/appraisal/questions/:studentId — Get Appraisal Form Rubric Questions for Student
🔒 Auth supervisor +4
API Purpose: Retrieves the standard annual appraisal template and evaluation criteria corresponding to the student's enrolled course and academic year.

📍 Website Flow Placement

Supervisor Appraisal Evaluation screen.

🔗 Dependencies & Prerequisites

Template seeded in `annual_appraisal_templates`.

⚖️ Validation & Business Rules

Matches student's `course_id` and `academic_year_number`.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
studentId path string (UUID) YES Student ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Rubric questions returned.
404 No active appraisal template found for this student's year.
Response Payload Structure
Field Type Description
form_title string Appraisal template name.
questions[].id string Question ID.
questions[].criterion string Competency criterion.
questions[].max_rating number Maximum score (e.g. 5).
Example Success Response (JSON)
{
  "form_title": "GNM 1st Year Annual Competency Assessment",
  "questions": [
    {
      "id": "q-aseptic-technique",
      "criterion": "Adherence to aseptic standards and infection control.",
      "max_rating": 5
    }
  ]
}
POST /api/appraisal/draft — Save Appraisal Evaluation Draft
🔒 Auth supervisor +1
API Purpose: Allows a supervisor to save interim scores and notes for a student's annual appraisal before final submission.

📍 Website Flow Placement

Supervisor Appraisal scoring -> 'Save Draft' button.

🔗 Dependencies & Prerequisites

Student enrollment.

⚖️ Validation & Business Rules

Status remains `draft`.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
studentId string (UUID) YES Student ID.
responses array YES Array of { question_id, score, remarks }.
remarks string OPT Overall supervisor remarks.
Example Request Payload (JSON)
{
  "studentId": "u-94820f12-88aa-4e12-b231-104928adbeef",
  "responses": [
    {
      "question_id": "q-aseptic-technique",
      "score": 5,
      "remarks": "Excellent compliance"
    }
  ],
  "remarks": "Progressing very well in clinical fundamentals."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Draft saved.
Response Payload Structure
Field Type Description
success boolean Outcome.
appraisalId string Draft appraisal ID.
Example Success Response (JSON)
{
  "success": true,
  "appraisalId": "appr-2026-9901"
}
POST /api/appraisal/:id/submit-to-hod — Submit Appraisal to Coordinator / HOD
🔒 Auth supervisor +1
API Purpose: Finalizes the supervisor's evaluation and routes the appraisal to the Year Coordinator / HOD for intermediate review.

📍 Website Flow Placement

Supervisor Appraisal sheet -> 'Submit Evaluation' button.

🔗 Dependencies & Prerequisites

Draft appraisal record.

⚖️ Validation & Business Rules

Sets status to `supervisor_evaluated` and timestamps submission.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Appraisal record ID.
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Submitted successfully.
Response Payload Structure
Field Type Description
success boolean Outcome.
message string Status.
Example Success Response (JSON)
{
  "success": true,
  "message": "Appraisal submitted to Coordinator for review."
}
POST /api/appraisal/:id/hod-verify — Coordinator / HOD Verify Appraisal
🔒 Auth hod +2
API Purpose: Endorses the appraisal and advances it to the Principal for final approval.

📍 Website Flow Placement

Coordinator Appraisal Review panel -> 'Verify & Forward' button.

🔗 Dependencies & Prerequisites

Appraisal in `supervisor_evaluated` status.

⚖️ Validation & Business Rules

Sets status to `hod_verified`.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Appraisal ID.
JSON Body Schema
Field Type Required Description
remarks string OPT Coordinator comments.
Example Request Payload (JSON)
{
  "remarks": "Verified against clinical logbook attendance criteria."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Verified and forwarded to Principal.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/appraisal/:id/hod-revision — Coordinator / HOD Request Revision
🔒 Auth hod +2
API Purpose: Returns the appraisal to the supervisor with feedback explaining required revisions or missing evidence.

📍 Website Flow Placement

Coordinator Review panel -> 'Request Revision' action.

🔗 Dependencies & Prerequisites

Appraisal record.

⚖️ Validation & Business Rules

Sets status to `revision_requested` and notifies supervisor.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Appraisal ID.
JSON Body Schema
Field Type Required Description
remarks string YES Mandatory revision instructions.
Example Request Payload (JSON)
{
  "remarks": "Please verify cannulation competency logs before rating section 2."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Appraisal returned for revision.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/appraisal/:id/principal-approve — Principal Final Sign-off on Appraisal
🔒 Auth principal +1
API Purpose: Executes executive institutional approval on the annual appraisal. Satisfies the mandatory appraisal condition required for student academic promotion.

📍 Website Flow Placement

Principal Dashboard -> Appraisal Approval queue -> 'Approve' button.

🔗 Dependencies & Prerequisites

Appraisal must be in `hod_verified` status.

⚖️ Validation & Business Rules

Sets status to `principal_approved`, records `principal_approved_at = NOW()`, unlocking promotion.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Appraisal ID.
JSON Body Schema
Field Type Required Description
remarks string OPT Principal final remarks.
Example Request Payload (JSON)
{
  "remarks": "Approved for progression to Year 2."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Appraisal approved by Principal.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/appraisal/:id/principal-return — Principal Return Appraisal for Re-evaluation
🔒 Auth principal +1
API Purpose: Rejects or returns an appraisal back to the coordinator/supervisor.

📍 Website Flow Placement

Principal Appraisal Review queue -> 'Return' button.

🔗 Dependencies & Prerequisites

Appraisal record.

⚖️ Validation & Business Rules

Sets status to `revision_requested`.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Appraisal ID.
JSON Body Schema
Field Type Required Description
remarks string YES Return reason.
Example Request Payload (JSON)
{
  "remarks": "Discrepancy in clinical ward hours. Please re-audit."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Returned for revision.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/promotion/eligibility/:studentId — Check Student Promotion Eligibility
🔒 Auth principal +4
API Purpose: Audits whether a student has completed their current academic year and is eligible for promotion. Checks active enrollment, maximum course duration (2 years for ANM, 3 years for GNM), and verified Principal approval on the annual appraisal.

📍 Website Flow Placement

Principal / Coordinator Promotion panel -> Select Student -> View Eligibility card.

🔗 Dependencies & Prerequisites

Requires active enrollment and appraisal records.

⚖️ Validation & Business Rules

Course duration check: ANM max 2 years, GNM max 3 years. Rejects promotion if appraisal is not in `principal_approved` state.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
studentId path string (UUID) YES Student user ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Eligibility audited successfully.
404 Student or active enrollment not found.
Response Payload Structure
Field Type Description
eligible boolean True if student can be promoted to next year.
currentYear number Active year (e.g. 1).
nextYear number | null Proposed next year (e.g. 2), or null if graduating.
isFinalYear boolean True if student is in final course year (GNM Year 3, ANM Year 2).
appraisalApproved boolean Whether principal-approved appraisal exists.
reason string | null Explanation if not eligible.
Example Success Response (JSON)
{
  "eligible": true,
  "currentYear": 1,
  "nextYear": 2,
  "isFinalYear": false,
  "appraisalApproved": true,
  "reason": null
}
POST /api/promotion/promote — Promote Student to Next Academic Year
🔒 Auth principal +1
API Purpose: Executes official promotion for an eligible student. In a single database transaction: archives current year enrollment as 'completed', creates Year N+1 enrollment record with 'active' status, assigns Year N+1 Coordinator, logs promotion history audit, and updates student profile.

📍 Website Flow Placement

Principal Portal -> Academic Promotion panel -> 'Promote Student' action button.

🔗 Dependencies & Prerequisites

Verified eligibility via `/api/promotion/eligibility/:studentId`.

⚖️ Validation & Business Rules

Atomic transaction. Previous enrollment status set to 'completed'. New enrollment created with status 'active'. Links to Year N+1 Coordinator. Promotion audit record saved in `student_promotion_history`.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
studentId string (UUID) YES Student user ID to promote.
remarks string OPT Promotion endorsement notes.
Example Request Payload (JSON)
{
  "studentId": "u-94820f12-88aa-4e12-b231-104928adbeef",
  "remarks": "Successfully cleared GNM Year 1 exams and annual clinical appraisal."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Student promoted successfully.
400 Student is not eligible for promotion (appraisal missing or incomplete).
403 Student belongs to a different college.
Response Payload Structure
Field Type Description
success boolean Promotion outcome.
message string Confirmation details.
previousYear number Archived academic year.
newYear number New active academic year.
newEnrollmentId string Newly created enrollment UUID.
Example Success Response (JSON)
{
  "success": true,
  "message": "Student promoted to Year 2 successfully",
  "previousYear": 1,
  "newYear": 2,
  "newEnrollmentId": "sae-yr2-1029-4411"
}
GET /api/promotion/history/:studentId — Get Student Academic Progression & Promotion History
🔒 Auth principal +4
API Purpose: Returns complete historical audit trail of student promotions, year transitions, approving principals, and completion timestamps.

📍 Website Flow Placement

Student Profile -> Academic Progression tab; Principal Audit view.

🔗 Dependencies & Prerequisites

Promotion history table.

⚖️ Validation & Business Rules

Ordered chronologically by `promoted_at` DESC.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
studentId path string (UUID) YES Student ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Progression history returned.
Response Payload Structure
Field Type Description
[].id string History record ID.
[].from_year number Previous year.
[].to_year number New year.
[].promoted_by_name string Principal who authorized promotion.
[].promoted_at string (ISO Date) Date of promotion.
[].remarks string | null Endorsement remarks.
Example Success Response (JSON)
[
  {
    "id": "ph-2026-001",
    "from_year": 1,
    "to_year": 2,
    "promoted_by_name": "Dr. K. S. Mann (Principal)",
    "promoted_at": "2026-09-29T10:00:00.000Z",
    "remarks": "Successfully cleared GNM Year 1 exams and annual clinical appraisal."
  }
]

10. Clinical Activities, Logbook & Competencies

Clinical procedure tracking, competency rubrics, dynamic procedure forms, category hierarchies, and submission evaluation lifecycles.

35 APIs
GET /api/activities — List Activity Submissions
🔒 Auth All Authenticated Roles
API Purpose: Retrieves student activity submissions with comprehensive filtering by status, subject, date range, or competency.

📍 Website Flow Placement

Student Activity Logbook; Supervisor review grid.

🔗 Dependencies & Prerequisites

Student enrollment.

⚖️ Validation & Business Rules

Students view own records; supervisors view assigned cohort.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
status query string OPT Filter: 'draft', 'submitted', 'approved', 'rejected'.
year query number OPT Academic year.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Activities returned.
Response Payload Structure
Field Type Description
[].id string Activity ID.
[].activity_date string Date performed.
[].status string Review status.
Example Success Response (JSON)
[
  {
    "id": "act-01",
    "activity_date": "2026-09-28",
    "status": "approved"
  }
]
POST /api/activities — Create Clinical Activity Submission
🔒 Auth student
API Purpose: Creates a new clinical procedure log entry with form data, patient context, and self-reflection.

📍 Website Flow Placement

New Log Entry modal.

🔗 Dependencies & Prerequisites

Active subject teacher.

⚖️ Validation & Business Rules

Sets initial status to 'submitted'.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
activity_date string YES Procedure date (YYYY-MM-DD).
subject_id string YES Subject ID.
competency_id string OPT Competency ID.
clinical_notes string YES Observations.
Example Request Payload (JSON)
{
  "activity_date": "2026-09-29",
  "subject_id": "sub-gnm1-found",
  "clinical_notes": "Nasogastric tube insertion under sterile technique."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
400 Invalid input.
Response Payload Structure
Field Type Description
id string Created ID.
Example Success Response (JSON)
{
  "id": "act-9912"
}
GET /api/activities/:id — Get Single Activity Details
🔒 Auth All Authenticated Roles
API Purpose: Retrieves complete record of a specific clinical activity including evaluation score and remarks.

📍 Website Flow Placement

Activity details drawer.

🔗 Dependencies & Prerequisites

Record ID.

⚖️ Validation & Business Rules

Must be owner or authorized teacher.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Activity ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Found.
404 Not found.
Response Payload Structure
Field Type Description
id string ID.
Example Success Response (JSON)
{
  "id": "act-9912",
  "status": "approved",
  "clinical_notes": "NG tube insertion."
}
PUT /api/activities/:id — Update Activity Submission
🔒 Auth student
API Purpose: Modifies fields of an unapproved activity log.

📍 Website Flow Placement

Edit activity screen.

🔗 Dependencies & Prerequisites

Owned activity.

⚖️ Validation & Business Rules

Cannot update once approved.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Activity ID.
JSON Body Schema
Field Type Required Description
clinical_notes string OPT Updated notes.
Example Request Payload (JSON)
{
  "clinical_notes": "Corrected procedure notes."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/activities/:id — Delete Draft Activity
🔒 Auth student +1
API Purpose: Removes an unsubmitted draft activity log.

📍 Website Flow Placement

Delete button on draft log.

🔗 Dependencies & Prerequisites

Draft entry.

⚖️ Validation & Business Rules

Only draft entries may be deleted by students.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Activity ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Status.
Example Success Response (JSON)
{
  "success": true
}
POST /api/activities/:id/reattempt — Reattempt Rejected Activity
🔒 Auth student
API Purpose: Creates a reattempt linked to a previously rejected activity submission.

📍 Website Flow Placement

Rejected Activity -> 'Reattempt' action.

🔗 Dependencies & Prerequisites

Rejected activity.

⚖️ Validation & Business Rules

Links parent activity ID in audit trail.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Previous activity ID.
JSON Body Schema
Field Type Required Description
clinical_notes string YES New procedure documentation.
Example Request Payload (JSON)
{
  "clinical_notes": "Repeat attempt at catheterization under direct observation."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Reattempt created.
Response Payload Structure
Field Type Description
success boolean Status.
new_activity_id string New ID.
Example Success Response (JSON)
{
  "success": true,
  "new_activity_id": "act-9913"
}
GET /api/activities/:id/history — Get Activity Audit History
🔒 Auth All Authenticated Roles
API Purpose: Returns complete version and review timeline for an activity submission.

📍 Website Flow Placement

Activity History drawer.

🔗 Dependencies & Prerequisites

Activity record.

⚖️ Validation & Business Rules

Read-only timeline.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Activity ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 History returned.
Response Payload Structure
Field Type Description
[].status string State transition.
[].created_at string Timestamp.
Example Success Response (JSON)
[
  {
    "status": "submitted",
    "created_at": "2026-09-29T09:00:00Z"
  }
]
GET /api/activities/supervisor/activities — List Activities for Supervisor Review
🔒 Auth supervisor +4
API Purpose: Returns activity submissions for subjects supervised by authenticated teacher.

📍 Website Flow Placement

Supervisor Review Table.

🔗 Dependencies & Prerequisites

Subject assignment.

⚖️ Validation & Business Rules

Authorized subjects only.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 List returned.
Example Success Response (JSON)
[]
PUT /api/activities/supervisor/activities/:id/review — Submit Supervisor Review on Activity
🔒 Auth supervisor +4
API Purpose: Records rating, approval status, and remarks from clinical supervisor.

📍 Website Flow Placement

Supervisor Evaluation modal.

🔗 Dependencies & Prerequisites

Authorized subject.

⚖️ Validation & Business Rules

Rating must be 1 to 5.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Activity ID.
JSON Body Schema
Field Type Required Description
status string YES 'approved' | 'rejected' | 'revision_requested'.
supervisor_rating number YES Score (1-5).
supervisor_feedback string OPT Feedback notes.
Example Request Payload (JSON)
{
  "status": "approved",
  "supervisor_rating": 4,
  "supervisor_feedback": "Well executed."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Review saved.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
PUT /api/activities/faculty/activities/:id/review — Submit Faculty Review on Activity
🔒 Auth faculty +2
API Purpose: Secondary faculty review endpoint for departmental instructors.

📍 Website Flow Placement

Faculty Review screen.

🔗 Dependencies & Prerequisites

Activity record.

⚖️ Validation & Business Rules

Faculty permissions required.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Activity ID.
JSON Body Schema
Field Type Required Description
status string YES 'approved' | 'rejected'.
Example Request Payload (JSON)
{
  "status": "approved"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Saved.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/activities/templates — List Dynamic Activity Templates
🔒 Auth All Authenticated Roles
API Purpose: Retrieves procedure form templates configured in system.

📍 Website Flow Placement

Logbook form builder.

🔗 Dependencies & Prerequisites

Master templates.

⚖️ Validation & Business Rules

Active templates only.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Templates returned.
Response Payload Structure
Field Type Description
[].id string Template ID.
[].title string Title.
Example Success Response (JSON)
[
  {
    "id": "tmpl-01",
    "title": "Vital Signs Recording Form"
  }
]
POST /api/activities/templates — Create Activity Template
🔒 Auth superadmin +1
API Purpose: Creates a new dynamic procedure form template.

📍 Website Flow Placement

Admin Form Builder.

🔗 Dependencies & Prerequisites

Admin rights.

⚖️ Validation & Business Rules

Unique title.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
title string YES Template name.
Example Request Payload (JSON)
{
  "title": "Pediatric Immunization Record"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
Response Payload Structure
Field Type Description
id string Created ID.
Example Success Response (JSON)
{
  "id": "tmpl-02"
}
GET /api/activities/templates/:id — Get Single Activity Template
🔒 Auth All Authenticated Roles
API Purpose: Returns schema and field definitions for a form template.

📍 Website Flow Placement

Form Renderer.

🔗 Dependencies & Prerequisites

Template ID.

⚖️ Validation & Business Rules

Read-only.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Template ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Found.
Response Payload Structure
Field Type Description
id string Template ID.
Example Success Response (JSON)
{
  "id": "tmpl-01",
  "title": "Vital Signs"
}
PUT /api/activities/templates/:id — Update Activity Template
🔒 Auth superadmin +1
API Purpose: Updates layout or title of a procedure template.

📍 Website Flow Placement

Form Editor.

🔗 Dependencies & Prerequisites

Template ID.

⚖️ Validation & Business Rules

Admin check.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Template ID.
JSON Body Schema
Field Type Required Description
title string YES New title.
Example Request Payload (JSON)
{
  "title": "Updated Template Title"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/activities/templates/:id — Delete Activity Template
🔒 Auth superadmin
API Purpose: Deactivates or deletes an activity template.

📍 Website Flow Placement

Form Builder Delete.

🔗 Dependencies & Prerequisites

Template ID.

⚖️ Validation & Business Rules

Cannot delete if referenced by existing student submissions.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Template ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/activities/templates/:id/duplicate — Duplicate Activity Template
🔒 Auth superadmin +1
API Purpose: Clones a procedure template along with all its dynamic fields.

📍 Website Flow Placement

Clone Template button.

🔗 Dependencies & Prerequisites

Source template.

⚖️ Validation & Business Rules

Appends '(Copy)' to title.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Template ID.
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Cloned.
Response Payload Structure
Field Type Description
id string Cloned ID.
Example Success Response (JSON)
{
  "id": "tmpl-01-copy"
}
GET /api/activities/templates/:templateId/fields — Get Fields for Template
🔒 Auth All Authenticated Roles
API Purpose: Lists all dynamic question fields within a template.

📍 Website Flow Placement

Form Renderer.

🔗 Dependencies & Prerequisites

Template ID.

⚖️ Validation & Business Rules

Ordered by sequence.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
templateId path string YES Template ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Fields returned.
Response Payload Structure
Field Type Description
[].field_key string Field key.
Example Success Response (JSON)
[
  {
    "field_key": "systolic_bp"
  }
]
POST /api/activities/templates/:templateId/fields — Add Field to Template
🔒 Auth superadmin +1
API Purpose: Appends a new input field (text, number, select, checkbox) to a procedure template.

📍 Website Flow Placement

Form Builder -> Add Field.

🔗 Dependencies & Prerequisites

Template ID.

⚖️ Validation & Business Rules

Field key must be unique per template.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
templateId path string YES Template ID.
JSON Body Schema
Field Type Required Description
field_key string YES Slug.
field_type string YES 'text', 'number', 'select'.
Example Request Payload (JSON)
{
  "field_key": "pulse_rate",
  "field_type": "number"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Added.
Response Payload Structure
Field Type Description
id string Created field ID.
Example Success Response (JSON)
{
  "id": "f-101"
}
GET /api/activities/fields — List All Global Fields
🔒 Auth All Authenticated Roles
API Purpose: Returns reusable field dictionary across templates.

📍 Website Flow Placement

Global fields browser.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Read-only.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Fields returned.
Example Success Response (JSON)
[]
PUT /api/activities/fields/:id — Update Field Definition
🔒 Auth superadmin
API Purpose: Modifies field label or validation rules.

📍 Website Flow Placement

Field settings.

🔗 Dependencies & Prerequisites

Field ID.

⚖️ Validation & Business Rules

Admin only.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Field ID.
JSON Body Schema
Field Type Required Description
label string YES Updated label.
Example Request Payload (JSON)
{
  "label": "Pulse Rate (bpm)"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/activities/fields/:id — Delete Field
🔒 Auth superadmin
API Purpose: Removes a field from template.

📍 Website Flow Placement

Field delete action.

🔗 Dependencies & Prerequisites

Field ID.

⚖️ Validation & Business Rules

Checks for existing response dependencies.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Field ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/activities/categories — List Activity Categories
🔒 Auth All Authenticated Roles
API Purpose: Returns activity sub-specialty categories (e.g. Inpatient, Emergency, Antenatal).

📍 Website Flow Placement

Logbook Category selector.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Sorted alphabetically.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Categories returned.
Response Payload Structure
Field Type Description
[].id string Category ID.
[].name string Name.
Example Success Response (JSON)
[
  {
    "id": "cat-01",
    "name": "Labor & Delivery"
  }
]
POST /api/activities/categories — Create Activity Category
🔒 Auth superadmin +1
API Purpose: Adds a new category for grouping procedures.

📍 Website Flow Placement

Admin Category management.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

Unique title.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
name string YES Category title.
Example Request Payload (JSON)
{
  "name": "Neonatal Intensive Care"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
Response Payload Structure
Field Type Description
id string Created ID.
Example Success Response (JSON)
{
  "id": "cat-02"
}
PUT /api/activities/categories/:id — Update Activity Category
🔒 Auth superadmin +1
API Purpose: Renames or modifies category properties.

📍 Website Flow Placement

Edit category modal.

🔗 Dependencies & Prerequisites

Category ID.

⚖️ Validation & Business Rules

Admin check.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Category ID.
JSON Body Schema
Field Type Required Description
name string YES Name.
Example Request Payload (JSON)
{
  "name": "NICU & Special Care Nursery"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/activities/categories/:id — Delete Activity Category
🔒 Auth superadmin
API Purpose: Deletes an unused category.

📍 Website Flow Placement

Delete category.

🔗 Dependencies & Prerequisites

Category ID.

⚖️ Validation & Business Rules

Cannot delete if activities link to it.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Category ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/activities/competencies — List Curriculum Competencies
🔒 Auth All Authenticated Roles
API Purpose: Returns accredited clinical competencies mapped to subjects and academic years.

📍 Website Flow Placement

Logbook Entry Competency dropdown.

🔗 Dependencies & Prerequisites

Subject link.

⚖️ Validation & Business Rules

Active competencies only.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
subject_id query string OPT Filter by subject.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Competencies returned.
Response Payload Structure
Field Type Description
[].id string Competency ID.
[].code string Code.
[].title string Title.
Example Success Response (JSON)
[
  {
    "id": "comp-01",
    "code": "N-101",
    "title": "Vital Signs Assessment"
  }
]
GET /api/activities/activity-types — List Activity Types
🔒 Auth All Authenticated Roles
API Purpose: Retrieves higher-level activity domain types.

📍 Website Flow Placement

Activity classification.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Read-only.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Types returned.
Response Payload Structure
Field Type Description
[].id string Type ID.
[].name string Title.
Example Success Response (JSON)
[
  {
    "id": "at-01",
    "name": "Inpatient Ward Practice"
  }
]
POST /api/activities/activity-types — Create Activity Type
🔒 Auth superadmin +1
API Purpose: Adds a new activity type classification.

📍 Website Flow Placement

Admin Activity Types panel.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

Unique title.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
name string YES Title.
Example Request Payload (JSON)
{
  "name": "Community Outreach Health Camp"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
Response Payload Structure
Field Type Description
id string Created ID.
Example Success Response (JSON)
{
  "id": "at-02"
}
PUT /api/activities/activity-types/:id — Update Activity Type
🔒 Auth superadmin +1
API Purpose: Updates an existing activity type.

📍 Website Flow Placement

Admin Edit Type.

🔗 Dependencies & Prerequisites

Type ID.

⚖️ Validation & Business Rules

Admin check.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Type ID.
JSON Body Schema
Field Type Required Description
name string YES Title.
Example Request Payload (JSON)
{
  "name": "Community Health Nursing Fieldwork"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/activities/activity-types/:id — Delete Activity Type
🔒 Auth superadmin
API Purpose: Removes an activity type.

📍 Website Flow Placement

Admin Delete Type.

🔗 Dependencies & Prerequisites

Type ID.

⚖️ Validation & Business Rules

Blocked if referenced.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Type ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/activities/activity-types/:id/duplicate — Duplicate Activity Type
🔒 Auth superadmin +1
API Purpose: Duplicates an activity type classification and its linked categories.

📍 Website Flow Placement

Admin Clone Type.

🔗 Dependencies & Prerequisites

Type ID.

⚖️ Validation & Business Rules

Deep copies child categories.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Type ID.
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Duplicated.
Response Payload Structure
Field Type Description
id string New ID.
Example Success Response (JSON)
{
  "id": "at-02-copy"
}
GET /api/logbook — List Logbook Entries (Legacy Alias)
🔒 Auth student +2
API Purpose: Retrieves student logbook entries (compatible legacy endpoint).

📍 Website Flow Placement

Legacy Logbook view.

🔗 Dependencies & Prerequisites

Student profile.

⚖️ Validation & Business Rules

Maps to activities table.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Entries returned.
Example Success Response (JSON)
[]
POST /api/logbook — Create Logbook Entry (Legacy Alias)
🔒 Auth student
API Purpose: Creates a logbook record.

📍 Website Flow Placement

Legacy submission.

🔗 Dependencies & Prerequisites

Active enrollment.

⚖️ Validation & Business Rules

Routes to activity insertion.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
notes string YES Notes.
Example Request Payload (JSON)
{
  "notes": "Wound dressing performed."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
Response Payload Structure
Field Type Description
id string ID.
Example Success Response (JSON)
{
  "id": "lb-01"
}
PATCH /api/logbook/:id — Update Logbook Entry (Legacy Alias)
🔒 Auth student
API Purpose: Updates an existing logbook entry.

📍 Website Flow Placement

Legacy edit.

🔗 Dependencies & Prerequisites

Entry ID.

⚖️ Validation & Business Rules

Unapproved only.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Entry ID.
JSON Body Schema
Field Type Required Description
notes string OPT Notes.
Example Request Payload (JSON)
{
  "notes": "Updated wound notes."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Status.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/logbook/:id — Delete Logbook Entry (Legacy Alias)
🔒 Auth student +1
API Purpose: Removes an unapproved logbook entry.

📍 Website Flow Placement

Legacy delete.

🔗 Dependencies & Prerequisites

Entry ID.

⚖️ Validation & Business Rules

Ownership check.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Entry ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Status.
Example Success Response (JSON)
{
  "success": true
}

11. Clinical Cohort Assignments, Geofencing & Reviews

Scheduled cohort task assignments, GPS location geofence enforcement, multi-step drafts and multi-tier evaluation queues.

20 APIs
POST /api/assignments — Create Clinical Cohort Assignment
🔒 Auth supervisor +3
API Purpose: Assigns a specific clinical procedure or ward duty to a cohort of eligible students.

📍 Website Flow Placement

Supervisor -> 'Assign Task to Cohort' modal.

🔗 Dependencies & Prerequisites

Teacher subject assignment.

⚖️ Validation & Business Rules

Students must belong to teacher's academic cohort.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
title string YES Duty / procedure assignment title.
subject_id string YES Subject ID.
due_date string YES Due date (YYYY-MM-DD).
student_ids string[] YES List of student IDs to assign.
Example Request Payload (JSON)
{
  "title": "Night Duty Ward Vitals & Intake/Output Charting",
  "subject_id": "sub-gnm1-found",
  "due_date": "2026-10-05",
  "student_ids": [
    "u-94820f12-88aa-4e12-b231-104928adbeef"
  ]
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Assignment created.
Response Payload Structure
Field Type Description
id string Assignment ID.
Example Success Response (JSON)
{
  "id": "asgn-01"
}
GET /api/assignments — List Clinical Cohort Assignments
🔒 Auth All Authenticated Roles
API Purpose: Retrieves active clinical duty assignments for students or supervisors.

📍 Website Flow Placement

Clinical Tasks list view.

🔗 Dependencies & Prerequisites

Enrollment.

⚖️ Validation & Business Rules

Scoped to user's college.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Assignments returned.
Response Payload Structure
Field Type Description
[].id string ID.
[].title string Title.
Example Success Response (JSON)
[
  {
    "id": "asgn-01",
    "title": "Ward Duty Vitals"
  }
]
GET /api/assignments/:id/students — List Students Assigned to Task
🔒 Auth supervisor +3
API Purpose: Returns student roster and submission statuses for a specific duty assignment.

📍 Website Flow Placement

Assignment monitor drawer.

🔗 Dependencies & Prerequisites

Assignment ID.

⚖️ Validation & Business Rules

Supervisor check.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Assignment ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Roster returned.
Response Payload Structure
Field Type Description
[].student_name string Name.
[].has_submitted boolean Submitted status.
Example Success Response (JSON)
[
  {
    "student_name": "Simran Kaur",
    "has_submitted": true
  }
]
GET /api/assignments/eligible-students — List Eligible Students for Assignment
🔒 Auth supervisor +3
API Purpose: Returns students available for cohort assignment by department and academic year.

📍 Website Flow Placement

Assign Task student picker.

🔗 Dependencies & Prerequisites

Cohort linkage.

⚖️ Validation & Business Rules

Filters active students.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
department_id query string YES Department ID.
year query number YES Academic year.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Eligible students returned.
Response Payload Structure
Field Type Description
[].id string Student ID.
[].full_name string Name.
Example Success Response (JSON)
[
  {
    "id": "u-94820f12",
    "full_name": "Simran Kaur"
  }
]
DELETE /api/assignments/:id — Delete Assignment
🔒 Auth supervisor +3
API Purpose: Cancels and deletes a scheduled duty assignment.

📍 Website Flow Placement

Assignment delete action.

🔗 Dependencies & Prerequisites

Assignment ID.

⚖️ Validation & Business Rules

Only creator or admin.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Assignment ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/location/campus — Get College / Hospital Geofence Boundaries
🔒 Auth student
API Purpose: Returns GPS center coordinates and allowed radius (in meters) for clinical posting site.

📍 Website Flow Placement

Student submission GPS check.

🔗 Dependencies & Prerequisites

College / hospital location.

⚖️ Validation & Business Rules

Haversine formula validation.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Coordinates returned.
Response Payload Structure
Field Type Description
latitude number Center latitude.
longitude number Center longitude.
radius number Radius in meters (e.g. 500m).
Example Success Response (JSON)
{
  "latitude": 30.3398,
  "longitude": 76.3869,
  "radius": 500
}
GET /api/location/assignment/:assignmentId — Get Task Specific Geofence
🔒 Auth All Authenticated Roles
API Purpose: Returns specific clinical ward or hospital coordinate requirements for an assignment.

📍 Website Flow Placement

Task preparation modal.

🔗 Dependencies & Prerequisites

Assignment ID.

⚖️ Validation & Business Rules

Checks assignment configuration.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
assignmentId path string YES Assignment ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Location requirements returned.
Response Payload Structure
Field Type Description
has_location_restriction boolean Whether GPS required.
Example Success Response (JSON)
{
  "has_location_restriction": true,
  "latitude": 30.3398,
  "longitude": 76.3869,
  "radius": 500
}
POST /api/location/verify — Verify Geofenced Clinical Presence
🔒 Auth student
API Purpose: Validates device GPS coordinates against the required hospital geofence before permitting clinical submission.

📍 Website Flow Placement

Student submission geocheck.

🔗 Dependencies & Prerequisites

Assignment location.

⚖️ Validation & Business Rules

Must be within radius tolerance.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
assignmentId string YES Task ID.
latitude number YES Device GPS latitude.
longitude number YES Device GPS longitude.
accuracy number YES Device accuracy in meters.
Example Request Payload (JSON)
{
  "assignmentId": "asgn-01",
  "latitude": 30.3399,
  "longitude": 76.3868,
  "accuracy": 12
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Verified.
400 Outside geofence.
Response Payload Structure
Field Type Description
verified boolean Whether within boundary.
distance_meters number Distance to center.
Example Success Response (JSON)
{
  "verified": true,
  "distance_meters": 24.5
}
POST /api/location/override — Supervisor Location Geofence Override
🔒 Auth supervisor +3
API Purpose: Allows supervisor to manually approve an off-site procedure submission (e.g. community health field home visit).

📍 Website Flow Placement

Supervisor Geofence Exemption dialog.

🔗 Dependencies & Prerequisites

Assignment ID.

⚖️ Validation & Business Rules

Audit trail recorded.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
assignmentId string YES Assignment ID.
studentId string YES Student ID.
reason string YES Exemption rationale.
Example Request Payload (JSON)
{
  "assignmentId": "asgn-01",
  "studentId": "u-94820f12",
  "reason": "Authorized rural health outreach."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Exemption granted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/submissions/:assignmentId/draft — Save Assignment Draft Submission
🔒 Auth student
API Purpose: Saves partial responses to a duty assignment.

📍 Website Flow Placement

Task Form -> 'Save Draft'.

🔗 Dependencies & Prerequisites

Assignment ID.

⚖️ Validation & Business Rules

Status set to 'draft'.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
assignmentId path string YES Task ID.
JSON Body Schema
Field Type Required Description
form_data object YES Form fields.
Example Request Payload (JSON)
{
  "form_data": {
    "bp_reading": "120/80"
  }
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Draft saved.
Response Payload Structure
Field Type Description
id string Draft submission ID.
Example Success Response (JSON)
{
  "id": "subm-01"
}
POST /api/submissions/:assignmentId/submit — Submit Assignment for Review
🔒 Auth student
API Purpose: Finalizes submission of a duty assignment for teacher grading.

📍 Website Flow Placement

Task Form -> 'Submit Task'.

🔗 Dependencies & Prerequisites

Assignment ID.

⚖️ Validation & Business Rules

Status set to 'submitted'.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
assignmentId path string YES Task ID.
JSON Body Schema
Field Type Required Description
form_data object YES Final responses.
Example Request Payload (JSON)
{
  "form_data": {
    "bp_reading": "120/80",
    "pulse": 74,
    "clinical_notes": "Routine check"
  }
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Submitted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/submissions/resubmit/:submissionId — Resubmit Revised Assignment
🔒 Auth student
API Purpose: Resubmits a task after addressing reviewer revision requests.

📍 Website Flow Placement

Resubmission modal.

🔗 Dependencies & Prerequisites

Submission in revision requested state.

⚖️ Validation & Business Rules

Resets review status.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
submissionId path string YES Previous submission ID.
JSON Body Schema
Field Type Required Description
form_data object YES Revised fields.
Example Request Payload (JSON)
{
  "form_data": {
    "clinical_notes": "Added medication charting."
  }
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Resubmitted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/submissions/:assignmentId/history — Get Assignment Submission History
🔒 Auth All Authenticated Roles
API Purpose: Returns historical versions and reviews of a student's task submission.

📍 Website Flow Placement

Submission Audit trail.

🔗 Dependencies & Prerequisites

Assignment ID.

⚖️ Validation & Business Rules

Read-only.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
assignmentId path string YES Assignment ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 History returned.
Example Success Response (JSON)
[]
GET /api/submissions/:submissionId — Get Specific Submission Record
🔒 Auth All Authenticated Roles
API Purpose: Returns complete responses and evaluation notes for a submission.

📍 Website Flow Placement

Submission viewer.

🔗 Dependencies & Prerequisites

Submission ID.

⚖️ Validation & Business Rules

Access check.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
submissionId path string YES Submission ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Found.
Response Payload Structure
Field Type Description
id string ID.
form_data object Data.
Example Success Response (JSON)
{
  "id": "subm-01",
  "form_data": {
    "bp_reading": "120/80"
  }
}
GET /api/review/queue — Get Multi-Tier Review Queue
🔒 Auth supervisor +4
API Purpose: Returns pending assignment submissions across all assigned duties for teacher grading.

📍 Website Flow Placement

Teacher Review Dashboard.

🔗 Dependencies & Prerequisites

Teacher assignment.

⚖️ Validation & Business Rules

Restricted to authorized cohorts.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Queue returned.
Response Payload Structure
Field Type Description
[].submission_id string Submission ID.
[].student_name string Student name.
Example Success Response (JSON)
[
  {
    "submission_id": "subm-01",
    "student_name": "Simran Kaur"
  }
]
POST /api/review/:submissionId/action — Execute Submission Review Action
🔒 Auth supervisor +4
API Purpose: Applies 'approve', 'reject', or 'revise' decision with remarks on a task submission.

📍 Website Flow Placement

Teacher Review Queue -> Action buttons.

🔗 Dependencies & Prerequisites

Submission ID.

⚖️ Validation & Business Rules

Notifies student.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
submissionId path string YES Submission ID.
JSON Body Schema
Field Type Required Description
action string YES 'approve' | 'reject' | 'revise'.
remarks string OPT Feedback notes.
Example Request Payload (JSON)
{
  "action": "approve",
  "remarks": "Vital charting correctly completed."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Action recorded.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/authority/assignments — Create Clinical Authority Assignment
🔒 Auth superadmin +1
API Purpose: Delegates institutional clinical evaluation authority to hospital preceptors.

📍 Website Flow Placement

Clinical Authority Setup.

🔗 Dependencies & Prerequisites

Hospital link.

⚖️ Validation & Business Rules

Hospital Admin check.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
authority_id string YES Preceptor user ID.
hospital_id string YES Hospital ID.
Example Request Payload (JSON)
{
  "authority_id": "u-prec-01",
  "hospital_id": "hosp-01"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
Response Payload Structure
Field Type Description
success boolean Status.
Example Success Response (JSON)
{
  "success": true
}
GET /api/authority/assignments — List Clinical Authority Assignments
🔒 Auth superadmin +5
API Purpose: Retrieves active clinical preceptor delegations.

📍 Website Flow Placement

Preceptor directory.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Institutional scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 List returned.
Example Success Response (JSON)
[]
GET /api/authority/resolve/:studentId — Resolve Student Evaluating Authority
🔒 Auth All Authenticated Roles
API Purpose: Determines the exact supervisory authority responsible for evaluating a student in a specific year.

📍 Website Flow Placement

Routing check during submission.

🔗 Dependencies & Prerequisites

Student ID.

⚖️ Validation & Business Rules

Resolves via subject assignments.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
studentId path string YES Student ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Authority resolved.
Response Payload Structure
Field Type Description
evaluating_authority string Resolved preceptor or teacher.
Example Success Response (JSON)
{
  "evaluating_authority": "Subject Dedicated Teachers"
}
GET /api/authority/history/:studentId — Get Authority Delegation History
🔒 Auth supervisor +4
API Purpose: Returns historical audit trail of preceptor delegations.

📍 Website Flow Placement

Authority audit screen.

🔗 Dependencies & Prerequisites

Student ID.

⚖️ Validation & Business Rules

Read-only.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
studentId path string YES Student ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 History returned.
Example Success Response (JSON)
[]

12. Leaves & Absences

Student and staff leave application, supervisor/coordinator recommendations, and executive institutional approvals.

4 APIs
GET /api/leaves — List Leave Applications
🔒 Auth All Authenticated Roles
API Purpose: Retrieves leave requests submitted by the student, or leave applications pending review by supervisor, coordinator, or principal.

📍 Website Flow Placement

Student Portal -> Leaves tab; Coordinator / Principal -> Leave Approvals view.

🔗 Dependencies & Prerequisites

Requires active user profile.

⚖️ Validation & Business Rules

Students view own leave applications; staff view leaves within their college/department.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
status query string OPT Filter: 'pending', 'approved', 'rejected'.
student_id query string OPT Filter by student (for staff).
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Leave requests returned.
Response Payload Structure
Field Type Description
[].id string Leave request UUID.
[].student_name string Applicant full name.
[].start_date string (Date) First day of leave.
[].end_date string (Date) Last day of leave.
[].reason string Reason for absence.
[].status string Current status: 'pending', 'approved', 'rejected'.
Example Success Response (JSON)
[
  {
    "id": "lv-1029-4411",
    "student_name": "Simran Kaur",
    "start_date": "2026-10-01",
    "end_date": "2026-10-03",
    "reason": "Attending sister&#39;s wedding in home town.",
    "status": "pending"
  }
]
POST /api/leaves — Apply for Leave of Absence
🔒 Auth student +1
API Purpose: Submits a formal leave request with reason, date range, and optional medical/leave certificate attachment.

📍 Website Flow Placement

Student Portal -> 'Apply Leave' modal.

🔗 Dependencies & Prerequisites

Student active enrollment.

⚖️ Validation & Business Rules

Sets initial status to 'pending'. Dates must be valid and chronologically correct.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
start_date string (YYYY-MM-DD) YES Start date.
end_date string (YYYY-MM-DD) YES End date.
reason string YES Detailed justification.
leave_type string OPT Type: 'medical', 'casual', 'duty'.
document_url string OPT Uploaded certificate file path.
Example Request Payload (JSON)
{
  "start_date": "2026-10-01",
  "end_date": "2026-10-03",
  "reason": "Attending sister&#39;s wedding in home town.",
  "leave_type": "casual"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Leave request submitted.
400 End date precedes start date or missing fields.
Response Payload Structure
Field Type Description
success boolean Outcome.
id string Created leave record ID.
Example Success Response (JSON)
{
  "success": true,
  "id": "lv-1029-4411"
}
PATCH /api/leaves/:id — Review / Update Leave Status
🔒 Auth supervisor +4
API Purpose: Approves or rejects a leave application with reviewer feedback remarks.

📍 Website Flow Placement

Leave Approvals table -> 'Approve' / 'Reject' button.

🔗 Dependencies & Prerequisites

Leave application ID.

⚖️ Validation & Business Rules

Notifies student via internal notifications.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Leave request ID.
JSON Body Schema
Field Type Required Description
status string YES 'approved' | 'rejected'.
remarks string OPT Reviewer comments.
Example Request Payload (JSON)
{
  "status": "approved",
  "remarks": "Leave sanctioned. Student must make up clinical hours upon return."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Leave status updated.
403 Unauthorized to resolve this leave.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/leaves/:id — Cancel / Delete Pending Leave Request
🔒 Auth student +1
API Purpose: Allows applicant to cancel a leave request while it is still in 'pending' status.

📍 Website Flow Placement

My Leaves list -> 'Cancel Request' button.

🔗 Dependencies & Prerequisites

Pending leave request owned by user.

⚖️ Validation & Business Rules

Only pending leaves can be deleted by student.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES Leave request ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Leave request cancelled.
409 Cannot cancel an already approved or rejected leave.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}

13. Payments & Fee Processing

Razorpay payment gateway integration, order generation, cryptographic signature validation, and institutional financial audit trails.

4 APIs
GET /api/payments/status — Check Student Enrollment Payment Status
🔒 Auth student
API Purpose: Verifies whether the student has completed the annual logbook portal subscription fee payment for their active academic year.

📍 Website Flow Placement

Student Portal initialization; Payment banner / barrier modal.

🔗 Dependencies & Prerequisites

Requires active student academic enrollment.

⚖️ Validation & Business Rules

Evaluates fee settlement in `payment_orders` or `payment_bypass` flag in `users`.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Payment status evaluated.
Response Payload Structure
Field Type Description
paid boolean True if annual fee is settled.
orderId string | null Razorpay order ID if pending.
amount number Fee amount in paise (e.g. 50000 = ₹500).
currency string Currency code (INR).
bypass boolean True if student has institutional fee waiver.
Example Success Response (JSON)
{
  "paid": true,
  "orderId": "order_Pnrc2026_9901",
  "amount": 50000,
  "currency": "INR",
  "bypass": false
}
POST /api/payments/create-order — Create Razorpay Payment Order
🔒 Auth student
API Purpose: Initiates a secure Razorpay order for the student's annual elogbook subscription fee.

📍 Website Flow Placement

Student Portal -> 'Pay Annual Fee' button -> Razorpay modal initialization.

🔗 Dependencies & Prerequisites

Requires active enrollment and Razorpay credentials configured in environment.

⚖️ Validation & Business Rules

Amount locked to official PNRC fee schedule.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
academicYear number OPT Academic year (default active year).
Example Request Payload (JSON)
{
  "academicYear": 1
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Order created successfully.
500 Payment gateway error.
Response Payload Structure
Field Type Description
orderId string Razorpay order ID (e.g. order_xxx).
amount number Amount in INR paise.
currency string 'INR'.
keyId string Public Razorpay API key for frontend checkout.
Example Success Response (JSON)
{
  "orderId": "order_Nsq1829dks91",
  "amount": 50000,
  "currency": "INR",
  "keyId": "rzp_live_example123"
}
POST /api/payments/verify — Verify Razorpay Payment Signature
🔒 Auth student
API Purpose: Validates HMAC-SHA256 signature returned by Razorpay checkout, records verified payment in database, and unlocks student portal features.

📍 Website Flow Placement

Razorpay Checkout callback (`onSuccess`).

🔗 Dependencies & Prerequisites

Valid order created via `/api/payments/create-order`.

⚖️ Validation & Business Rules

Cryptographically verifies signature using `RAZORPAY_KEY_SECRET`. Sets order status to 'paid'.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
razorpay_order_id string YES Order ID from gateway.
razorpay_payment_id string YES Transaction ID from gateway.
razorpay_signature string YES HMAC signature string.
Example Request Payload (JSON)
{
  "razorpay_order_id": "order_Nsq1829dks91",
  "razorpay_payment_id": "pay_Nsq2981ka99",
  "razorpay_signature": "9283749823749823749823749823749823749823749823749823749823749823"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Signature valid and payment recorded.
400 Signature mismatch or invalid order.
Response Payload Structure
Field Type Description
success boolean Verification outcome.
message string Confirmation notification.
Example Success Response (JSON)
{
  "success": true,
  "message": "Payment verified successfully. Account fully unlocked."
}
GET /api/payments/admin/all — Admin All Payments Audit Trail
🔒 Auth superadmin +1
API Purpose: Retrieves complete financial transaction log across all colleges and students for revenue auditing.

📍 Website Flow Placement

Superadmin / College Admin Financial Reports panel.

🔗 Dependencies & Prerequisites

Admin credentials.

⚖️ Validation & Business Rules

College Admin restricted to own college transactions.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
college_id query string OPT College filter.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Transaction history returned.
Response Payload Structure
Field Type Description
payments[].id string Payment ID.
payments[].student_name string Student name.
payments[].amount number Amount.
payments[].status string Status.
Example Success Response (JSON)
{
  "payments": [
    {
      "id": "pay-01",
      "student_name": "Simran Kaur",
      "amount": 500,
      "status": "captured"
    }
  ]
}

14. File Storage & Document Delivery

Multi-part document uploads (Aadhaar, PAN, PMC certificates, clinical images), file validation, secure multi-tenant access control, and authenticated streaming.

4 APIs
POST /api/upload — Upload Document or Clinical File
🔒 Auth All Authenticated Roles
API Purpose: Uploads an identity document, clinical report, or photo to secure storage (local or Amazon S3). Enforces strict MIME validation (JPEG, PNG, PDF only), size restrictions (max 10MB), and records file metadata.

📍 Website Flow Placement

Triggered whenever documents (Aadhaar, PAN, PMC certificate, activity evidence) are uploaded across the application.

🔗 Dependencies & Prerequisites

Requires active session.

⚖️ Validation & Business Rules

Magic-byte header inspection; strictly disallows executable scripts or SVG files. Saves record in `file_uploads`.

📥 Request Specification

Required Headers
Content-Type: multipart/form-data
JSON Body Schema
Field Type Required Description
file file (binary) YES File attachment (JPEG, PNG, or PDF up to 10MB).
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 File uploaded successfully.
400 No file provided in form-data.
415 Only valid JPEG, PNG, or PDF files are accepted.
429 Upload rate limit exceeded.
Response Payload Structure
Field Type Description
id string (UUID) Unique file identifier.
url string Relative proxy URL to retrieve the document (e.g. /uploads/userId/fileId.pdf).
mime_type string Verified MIME type.
size number Size in bytes.
Example Success Response (JSON)
{
  "id": "f-9988-1122-3344",
  "url": "/uploads/u-94820f12/f-9988-1122-3344.pdf",
  "mime_type": "application/pdf",
  "size": 412984
}
DELETE /api/upload/:id — Delete Uploaded File by ID
🔒 Auth All Authenticated Roles
API Purpose: Deletes an uploaded document from storage and marks the database record as deleted.

📍 Website Flow Placement

Document removal / re-upload button.

🔗 Dependencies & Prerequisites

File ID.

⚖️ Validation & Business Rules

Soft-deletes metadata in DB and purges storage object.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string (UUID) YES File upload ID to delete.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
204 File deleted successfully.
403 Access denied (file belongs to another user).
404 File not found.
Returns empty body (e.g. 204 No Content).
DELETE /api/upload — Delete File by URL Reference
🔒 Auth All Authenticated Roles
API Purpose: Alternative deletion endpoint accepting file URL reference.

📍 Website Flow Placement

Document replacement.

🔗 Dependencies & Prerequisites

File URL.

⚖️ Validation & Business Rules

Ownership verification.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
url string YES Relative file path URL to delete.
Example Request Payload (JSON)
{
  "url": "/uploads/u-94820f12/f-9988-1122-3344.pdf"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
204 File deleted.
403 Access denied.
Returns empty body (e.g. 204 No Content).
GET /uploads/:filename(*) — Authenticated Document Proxy Delivery
🔒 Auth All Authenticated Roles (Authorized Tenancy)
API Purpose: Securely streams an uploaded document or clinical attachment. Enforces institutional tenancy and supervisor authorization checks so confidential patient records, PAN, and Aadhaar documents are never exposed publicly or across colleges.

📍 Website Flow Placement

Document preview modal, PDF viewer, or image avatar display.

🔗 Dependencies & Prerequisites

Active authenticated session.

⚖️ Validation & Business Rules

Tenancy authorization: user must either own the file, supervise the student (via active enrollment or subject assignment), be college principal, or superadmin. Serves locally or proxies via S3 GetObjectCommand.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
filename path string YES File path reference.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 File streamed with Content-Disposition and nosniff headers.
401 Unauthorized / missing session token.
404 File not found or access denied.
Response Payload Structure
Field Type Description
binary stream image/png, image/jpeg, application/pdf Direct file stream with security headers.
Returns empty body (e.g. 204 No Content).

15. Dashboards & Real-time Metrics

Role-specific statistical rollups, activity velocity counters, competency completion progress, and operational indicators.

5 APIs
GET /api/dashboard/student-stats — Get Student Dashboard Metrics
🔒 Auth student
API Purpose: Calculates personal metrics for the logged-in student: total activities logged, approved count, pending review count, rejected count, clinical attendance days, and competency progress.

📍 Website Flow Placement

Student Dashboard top summary stat cards.

🔗 Dependencies & Prerequisites

Student profile.

⚖️ Validation & Business Rules

Scoped to `student_id = req.user.id`.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Metrics returned.
Response Payload Structure
Field Type Description
total_activities number Total logs created.
approved number Approved procedures.
pending number Pending review.
revision_requested number Revisions needed.
competencies_achieved number Accredited competencies completed.
Example Success Response (JSON)
{
  "total_activities": 38,
  "approved": 34,
  "pending": 3,
  "revision_requested": 1,
  "competencies_achieved": 22
}
GET /api/dashboard/supervisor-stats — Get Supervisor Dashboard Metrics
🔒 Auth supervisor +4
API Purpose: Returns total assigned students, submissions pending evaluation in teacher's subjects, reviews completed this month, and pending appraisals.

📍 Website Flow Placement

Supervisor Dashboard top summary cards.

🔗 Dependencies & Prerequisites

Assigned subjects.

⚖️ Validation & Business Rules

Restricted to teacher's subjects.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Supervisor metrics returned.
Response Payload Structure
Field Type Description
total_students number Students in cohort.
pending_reviews number Logs waiting for teacher review.
reviewed_today number Procedures evaluated today.
Example Success Response (JSON)
{
  "total_students": 45,
  "pending_reviews": 7,
  "reviewed_today": 12
}
GET /api/dashboard/coordinator-stats — Get Coordinator Dashboard Metrics
🔒 Auth coordinator +2
API Purpose: Calculates academic year cohort stats: total students in year, active subject teachers, registration requests pending, and overall year progression.

📍 Website Flow Placement

Year Coordinator Dashboard header.

🔗 Dependencies & Prerequisites

Coordinator assignment.

⚖️ Validation & Business Rules

Scoped to year cohort.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Coordinator metrics returned.
Response Payload Structure
Field Type Description
cohort_students number Students in coordinator's year.
pending_registrations number Unverified staff/students.
pending_appraisals number Appraisals awaiting endorsement.
Example Success Response (JSON)
{
  "cohort_students": 45,
  "pending_registrations": 2,
  "pending_appraisals": 5
}
GET /api/dashboard/faculty-stats — Get Faculty Departmental Stats
🔒 Auth faculty +2
API Purpose: Returns departmental metrics for instructors and faculty.

📍 Website Flow Placement

Faculty Portal overview.

🔗 Dependencies & Prerequisites

Department link.

⚖️ Validation & Business Rules

Department scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Metrics returned.
Example Success Response (JSON)
{
  "active_classes": 4,
  "evaluated_students": 38
}
GET /api/dashboard/hospital-stats — Get Clinical Hospital Stats
🔒 Auth hospital_admin +1
API Purpose: Returns clinical posting stats, active interns in hospital, and clinical preceptors.

📍 Website Flow Placement

Hospital Admin Portal overview.

🔗 Dependencies & Prerequisites

Hospital link.

⚖️ Validation & Business Rules

Hospital scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Hospital metrics returned.
Example Success Response (JSON)
{
  "active_interns": 28,
  "affiliated_colleges": 2
}

16. Notifications & Institutional Notices

In-app notifications, badge unread counters, institutional council bulletins, and college notices.

9 APIs
GET /api/notifications — Get User Notifications
🔒 Auth All Authenticated Roles
API Purpose: Retrieves in-app notifications for the authenticated user (e.g. activity reviewed, leave approved, appraisal signed).

📍 Website Flow Placement

Header Bell Icon dropdown.

🔗 Dependencies & Prerequisites

User profile.

⚖️ Validation & Business Rules

Ordered by `created_at` DESC.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
limit query number OPT Max count (default 20).
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Notifications returned.
Response Payload Structure
Field Type Description
[].id string Notification UUID.
[].title string Title.
[].message string Body text.
[].is_read boolean Read status.
[].created_at string Timestamp.
Example Success Response (JSON)
[
  {
    "id": "notif-01",
    "title": "Activity Approved",
    "message": "Dr. Harpreet Kaur approved your &#39;Fundamentals of Nursing&#39; logbook entry.",
    "is_read": false,
    "created_at": "2026-09-29T11:00:00Z"
  }
]
POST /api/notifications — Dispatch Notification
🔒 Auth supervisor +4
API Purpose: Sends an in-app notification to a user or cohort.

📍 Website Flow Placement

System events and staff announcements.

🔗 Dependencies & Prerequisites

Recipient user ID.

⚖️ Validation & Business Rules

Inserts into notifications table.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
userId string YES Target recipient user ID.
title string YES Notification title.
message string YES Message body.
Example Request Payload (JSON)
{
  "userId": "u-94820f12-88aa-4e12-b231-104928adbeef",
  "title": "Appraisal Signed",
  "message": "Your Year 1 Annual Appraisal has been approved by the Principal."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Notification dispatched.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
PATCH /api/notifications/:id/read — Mark Notification as Read
🔒 Auth All Authenticated Roles
API Purpose: Marks a notification as read and decrements unread counter.

📍 Website Flow Placement

Notification item click.

🔗 Dependencies & Prerequisites

Notification ID.

⚖️ Validation & Business Rules

Must belong to authenticated user.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Notification ID.
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Marked as read.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/notifications/sidebar-counts — Get Sidebar Unread & Task Counters
🔒 Auth All Authenticated Roles
API Purpose: Returns real-time badge counts for navigation tabs (unread notices, pending submissions, leaves).

📍 Website Flow Placement

Sidebar Navigation badges.

🔗 Dependencies & Prerequisites

Active user.

⚖️ Validation & Business Rules

Dynamic aggregation.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Counters returned.
Response Payload Structure
Field Type Description
unread_notifications number Unread notifications.
pending_reviews number Items needing review.
Example Success Response (JSON)
{
  "unread_notifications": 3,
  "pending_reviews": 5
}
GET /api/notices — List Active Institutional Notices
🔒 Auth All Authenticated Roles
API Purpose: Retrieves published announcements, circulars, and council exam alerts.

📍 Website Flow Placement

Dashboard Noticeboard widget.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active notices only (`is_active = 1`).

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Notices returned.
Response Payload Structure
Field Type Description
[].id string Notice ID.
[].title string Notice title.
[].content string Notice text.
[].created_at string Date published.
Example Success Response (JSON)
[
  {
    "id": "ntc-01",
    "title": "PNRC Annual Clinical Examination Schedule 2026",
    "content": "Examinations for GNM and ANM will commence from 15th October 2026.",
    "created_at": "2026-09-25T10:00:00Z"
  }
]
GET /api/notices/manage — List Notices for Management
🔒 Auth principal +2
API Purpose: Returns all notices including drafts and archived bulletins for administrators.

📍 Website Flow Placement

Noticeboard Manager.

🔗 Dependencies & Prerequisites

Admin rights.

⚖️ Validation & Business Rules

College scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 List returned.
Example Success Response (JSON)
[]
POST /api/notices — Publish Notice
🔒 Auth principal +2
API Purpose: Publishes a new bulletin or announcement.

📍 Website Flow Placement

Create Notice modal.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

Records publisher ID.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
title string YES Notice headline.
content string YES Detailed bulletin text.
Example Request Payload (JSON)
{
  "title": "Holiday Announcement - Gandhi Jayanti",
  "content": "The college and clinical wards will observe holiday on 2nd October."
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Published.
Response Payload Structure
Field Type Description
id string Created ID.
Example Success Response (JSON)
{
  "id": "ntc-02"
}
PATCH /api/notices/:id/toggle — Toggle Notice Active State
🔒 Auth principal +2
API Purpose: Activates or deactivates display of a notice.

📍 Website Flow Placement

Notice manager toggle switch.

🔗 Dependencies & Prerequisites

Notice ID.

⚖️ Validation & Business Rules

Flips `is_active`.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Notice ID.
Example Request Payload (JSON)
{}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Toggled.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/notices/:id — Delete Notice
🔒 Auth principal +2
API Purpose: Deletes a notice permanently.

📍 Website Flow Placement

Delete notice action.

🔗 Dependencies & Prerequisites

Notice ID.

⚖️ Validation & Business Rules

Admin check.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Notice ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}

17. Master Data & Academic Hierarchy

Curricular lookup entities (hospitals, colleges, courses, academic years, terms, subjects, competencies, dynamic tables) and academic structure trees.

23 APIs
GET /api/master/hospitals — List Affiliated Clinical Hospitals
🔒 Auth All Authenticated Roles
API Purpose: Returns accredited training hospitals and clinical facilities in Punjab.

📍 Website Flow Placement

Hospital dropdowns across student posting and supervisor setups.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active facilities only.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Hospitals list returned.
Response Payload Structure
Field Type Description
[].id string Hospital ID.
[].name string Hospital name.
Example Success Response (JSON)
[
  {
    "id": "hosp-01",
    "name": "Rajindra Hospital, Patiala"
  }
]
GET /api/master/colleges — List Nursing Colleges
🔒 Auth All Authenticated Roles
API Purpose: Returns accredited government and private nursing colleges under Punjab Nurses Registration Council.

📍 Website Flow Placement

Registration, onboarding, and superadmin filters.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Alphabetical order.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Colleges returned.
Response Payload Structure
Field Type Description
[].id string College ID.
[].name string College name.
Example Success Response (JSON)
[
  {
    "id": "col-1029-4411",
    "name": "Government College of Nursing, Patiala"
  }
]
GET /api/master/courses — List Nursing Programmes / Courses
🔒 Auth All Authenticated Roles
API Purpose: Returns academic courses (GNM - 3 years, ANM - 2 years).

📍 Website Flow Placement

Course selectors.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Returns active courses.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Courses returned.
Response Payload Structure
Field Type Description
[].id string Course ID.
[].name string Course title.
Example Success Response (JSON)
[
  {
    "id": "c-gnm-4411-8899-0011",
    "name": "General Nursing and Midwifery (GNM)"
  }
]
GET /api/master/departments — List Departments
🔒 Auth All Authenticated Roles
API Purpose: Returns academic departments.

📍 Website Flow Placement

Staff registration and assignments.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active records.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Departments returned.
Example Success Response (JSON)
[]
GET /api/master/years — List Academic Years
🔒 Auth All Authenticated Roles
API Purpose: Returns curriculum year definitions (Year 1, Year 2, Year 3).

📍 Website Flow Placement

Year selectors.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Standardized.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Years returned.
Example Success Response (JSON)
[]
GET /api/master/terms — List Terms / Semesters
🔒 Auth All Authenticated Roles
API Purpose: Returns academic term divisions.

📍 Website Flow Placement

Term filters.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active terms.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Terms returned.
Example Success Response (JSON)
[]
GET /api/master/subjects — List Subjects Master
🔒 Auth All Authenticated Roles
API Purpose: Retrieves course subjects, codes, and credit hours.

📍 Website Flow Placement

Curriculum mapping.

🔗 Dependencies & Prerequisites

Course / year.

⚖️ Validation & Business Rules

Enforces year linkage.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
year_id query string OPT Year filter.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Subjects returned.
Example Success Response (JSON)
[]
GET /api/master/competencies — List Master Competencies
🔒 Auth All Authenticated Roles
API Purpose: Retrieves accredited clinical competencies and nursing skill procedures.

📍 Website Flow Placement

Competency library.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Official syllabus.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Competencies returned.
Example Success Response (JSON)
[]
GET /api/master/activity_templates — List Activity Templates Master
🔒 Auth All Authenticated Roles
API Purpose: Returns master activity form templates.

📍 Website Flow Placement

Master data view.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Templates returned.
Example Success Response (JSON)
[]
GET /api/master/staff — List College Faculty & Staff
🔒 Auth All Authenticated Roles
API Purpose: Returns faculty members in user's institution.

📍 Website Flow Placement

Faculty selectors.

🔗 Dependencies & Prerequisites

College link.

⚖️ Validation & Business Rules

College scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Staff returned.
Example Success Response (JSON)
[]
GET /api/master/locations — List Clinical Hospital Locations
🔒 Auth All Authenticated Roles
API Purpose: Returns geofenced hospital coordinates.

📍 Website Flow Placement

Geofencing.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Validated coordinates.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Locations returned.
Example Success Response (JSON)
[]
POST /api/master/:table — Create Dynamic Master Record
🔒 Auth superadmin
API Purpose: Generic administrative endpoint to insert a record into allowed master tables.

📍 Website Flow Placement

Superadmin Master Table Manager.

🔗 Dependencies & Prerequisites

Superadmin role.

⚖️ Validation & Business Rules

Whitelisted tables only.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
table path string YES Allowed master table.
JSON Body Schema
Field Type Required Description
payload object YES Record attributes.
Example Request Payload (JSON)
{
  "name": "Community Health Nursing - II",
  "code": "GNM201"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
400 Disallowed table.
Response Payload Structure
Field Type Description
id string Created ID.
Example Success Response (JSON)
{
  "id": "sub-102"
}
PUT /api/master/:table/:id — Update Dynamic Master Record
🔒 Auth superadmin
API Purpose: Updates an existing master record.

📍 Website Flow Placement

Master Table Editor.

🔗 Dependencies & Prerequisites

Superadmin role.

⚖️ Validation & Business Rules

Whitelisted tables.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
table path string YES Table name.
id path string YES Record ID.
JSON Body Schema
Field Type Required Description
payload object YES Updated fields.
Example Request Payload (JSON)
{
  "name": "Updated Title"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/master/:table/:id — Delete Dynamic Master Record
🔒 Auth superadmin
API Purpose: Deletes a master record.

📍 Website Flow Placement

Master Table Delete.

🔗 Dependencies & Prerequisites

Superadmin role.

⚖️ Validation & Business Rules

Foreign key checks.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
table path string YES Table name.
id path string YES Record ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
GET /api/master/profiles — List Profiles Master
🔒 Auth superadmin +1
API Purpose: Administrative lookup of registered profiles.

📍 Website Flow Placement

Admin user picker.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

College scope.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Profiles returned.
Example Success Response (JSON)
[]
GET /api/academic/programmes — List Academic Programmes
🔒 Auth All Authenticated Roles
API Purpose: Returns academic courses in structural hierarchy.

📍 Website Flow Placement

Academic tree navigation.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Hierarchical.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Programmes returned.
Example Success Response (JSON)
[]
GET /api/academic/departments — List Academic Structure Departments
🔒 Auth All Authenticated Roles
API Purpose: Returns departments in structural tree.

📍 Website Flow Placement

Department tree.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Departments returned.
Example Success Response (JSON)
[]
GET /api/academic/years/:courseId — Get Academic Years for Course
🔒 Auth All Authenticated Roles
API Purpose: Returns years defined for a specific course (e.g. 2 years for ANM, 3 years for GNM).

📍 Website Flow Placement

Course year picker.

🔗 Dependencies & Prerequisites

Course ID.

⚖️ Validation & Business Rules

Filters by course.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
courseId path string YES Course ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Years returned.
Response Payload Structure
Field Type Description
[].year_number number Year (1, 2, 3).
Example Success Response (JSON)
[
  {
    "year_number": 1
  },
  {
    "year_number": 2
  },
  {
    "year_number": 3
  }
]
GET /api/academic/subjects/:yearId — Get Subjects for Academic Year
🔒 Auth All Authenticated Roles
API Purpose: Returns curriculum subjects belonging to an academic year.

📍 Website Flow Placement

Curriculum viewer.

🔗 Dependencies & Prerequisites

Year ID.

⚖️ Validation & Business Rules

Year linkage.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
yearId path string YES Year ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Subjects returned.
Example Success Response (JSON)
[]
GET /api/academic/terms/:yearId — Get Terms for Academic Year
🔒 Auth All Authenticated Roles
API Purpose: Returns terms defined for an academic year.

📍 Website Flow Placement

Term viewer.

🔗 Dependencies & Prerequisites

Year ID.

⚖️ Validation & Business Rules

Term linkage.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
yearId path string YES Year ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Terms returned.
Example Success Response (JSON)
[]
GET /api/academic/batches — List Student Batches
🔒 Auth All Authenticated Roles
API Purpose: Returns admission batches (e.g. 2024-2027, 2025-2028).

📍 Website Flow Placement

Batch picker.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Chronological.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Batches returned.
Example Success Response (JSON)
[]
GET /api/academic/sessions — List Academic Sessions
🔒 Auth All Authenticated Roles
API Purpose: Returns academic sessions.

📍 Website Flow Placement

Session picker.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active sessions.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Sessions returned.
Example Success Response (JSON)
[]
GET /api/academic/enrollment/:studentId — Get Student Historical Enrollments
🔒 Auth supervisor +5
API Purpose: Returns all historical academic year enrollments for a student.

📍 Website Flow Placement

Student Academic Progression sheet.

🔗 Dependencies & Prerequisites

Student ID.

⚖️ Validation & Business Rules

Access check.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
studentId path string YES Student ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Enrollments returned.
Example Success Response (JSON)
[]

18. Superadmin & System Administration

System-wide user administration, bulk provisioning, appraisal template configuration builder, fee bypass overrides, and enrollment repair utilities.

18 APIs
GET /api/admin/users — List System Users
🔒 Auth superadmin +2
API Purpose: Returns paginated user list with role, college, status, and verification state filters.

📍 Website Flow Placement

User Management table (`/admin/users`).

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

College admin restricted to own college.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
role query string OPT Filter by role.
search query string OPT Search by email or name.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Users list returned.
Response Payload Structure
Field Type Description
users[].id string User ID.
users[].email string Email.
users[].full_name string Name.
users[].role string Role.
users[].is_active boolean Active state.
Example Success Response (JSON)
{
  "users": [
    {
      "id": "u-94820f12",
      "email": "student@example.com",
      "full_name": "Simran Kaur",
      "role": "student",
      "is_active": true
    }
  ]
}
POST /api/admin/users — Create User Account (Admin)
🔒 Auth superadmin +5
API Purpose: Manually creates a new staff or student user account.

📍 Website Flow Placement

Create User modal.

🔗 Dependencies & Prerequisites

Admin permissions.

⚖️ Validation & Business Rules

Hashes password with bcrypt 12.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
email string YES Email.
full_name string YES Name.
role string YES Role.
password string YES Initial password.
Example Request Payload (JSON)
{
  "email": "prof.gurpreet@college.edu",
  "full_name": "Prof. Gurpreet Singh",
  "role": "supervisor",
  "password": "InitialPassword123!"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
Response Payload Structure
Field Type Description
id string Created user ID.
Example Success Response (JSON)
{
  "id": "u-prof-01"
}
PATCH /api/admin/users/:id/status — Toggle User Active / Suspended State
🔒 Auth superadmin +5
API Purpose: Activates or suspends a user's system access.

📍 Website Flow Placement

User status toggle switch.

🔗 Dependencies & Prerequisites

User ID.

⚖️ Validation & Business Rules

Cannot deactivate own account.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES User ID.
JSON Body Schema
Field Type Required Description
is_active boolean YES Active state.
Example Request Payload (JSON)
{
  "is_active": false
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Status updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
PATCH /api/admin/users/:id/reset-enrollment — Reset Student Academic Year Enrollment
🔒 Auth superadmin +1
API Purpose: Repairs student enrollment state in case of data inconsistencies.

📍 Website Flow Placement

Student Troubleshooting drawer.

🔗 Dependencies & Prerequisites

Student ID.

⚖️ Validation & Business Rules

Admin audit logged.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Student user ID.
JSON Body Schema
Field Type Required Description
academic_year_number number YES Target year (1, 2, 3).
Example Request Payload (JSON)
{
  "academic_year_number": 1
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Enrollment reset.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
PATCH /api/admin/users/:id — Update User Attributes
🔒 Auth superadmin +2
API Purpose: Updates name, email, or institutional assignments for a user.

📍 Website Flow Placement

Edit User modal.

🔗 Dependencies & Prerequisites

User ID.

⚖️ Validation & Business Rules

Admin check.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES User ID.
JSON Body Schema
Field Type Required Description
full_name string OPT New name.
Example Request Payload (JSON)
{
  "full_name": "Simran Kaur Sandhu"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
DELETE /api/admin/users/:id — Delete User Account
🔒 Auth superadmin +2
API Purpose: Soft-deletes user account and invalidates tokens.

📍 Website Flow Placement

Delete user action.

🔗 Dependencies & Prerequisites

User ID.

⚖️ Validation & Business Rules

Soft-delete.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES User ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/admin/users/bulk — Bulk Provision Users from CSV/JSON
🔒 Auth superadmin +2
API Purpose: Creates multiple student or staff accounts in a single batch operation.

📍 Website Flow Placement

Bulk Upload CSV tool.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

Rate limited.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
users array YES Array of user objects.
Example Request Payload (JSON)
{
  "users": [
    {
      "email": "student1@college.edu",
      "full_name": "Student 1",
      "role": "student"
    }
  ]
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Batch processed.
Response Payload Structure
Field Type Description
created_count number Created count.
Example Success Response (JSON)
{
  "created_count": 1
}
POST /api/admin/users/bulk-update — Bulk Update User Profiles
🔒 Auth superadmin +2
API Purpose: Batch updates multiple profiles.

📍 Website Flow Placement

Bulk Edit tool.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

Batch processed.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
updates array YES Updates array.
Example Request Payload (JSON)
{
  "updates": []
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
updated_count number Updated count.
Example Success Response (JSON)
{
  "updated_count": 0
}
GET /api/admin/registration-requests — Admin Registration Requests Roster
🔒 Auth superadmin +1
API Purpose: Superadmin global queue of pending registrations.

📍 Website Flow Placement

Global Registrations queue.

🔗 Dependencies & Prerequisites

Admin credentials.

⚖️ Validation & Business Rules

Superadmin sees all.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Requests returned.
Example Success Response (JSON)
[]
GET /api/admin/appraisal-form-configs — List Annual Appraisal Form Configurations
🔒 Auth superadmin +2
API Purpose: Returns all annual appraisal configurations and scoring rubrics.

📍 Website Flow Placement

Admin Appraisal Config Manager.

🔗 Dependencies & Prerequisites

None.

⚖️ Validation & Business Rules

Active templates.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Configurations returned.
Response Payload Structure
Field Type Description
[].id string Config ID.
[].form_name string Template title.
[].year_number number Year.
Example Success Response (JSON)
[
  {
    "id": "cfg-01",
    "form_name": "GNM 1st Year Annual Appraisal",
    "year_number": 1
  }
]
POST /api/admin/appraisal-form-configs — Create Annual Appraisal Configuration
🔒 Auth superadmin +1
API Purpose: Builds a new annual appraisal template for a course and academic year.

📍 Website Flow Placement

Appraisal Form Builder.

🔗 Dependencies & Prerequisites

Course ID.

⚖️ Validation & Business Rules

Superadmin only.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
form_name string YES Form title.
course_id string YES Course ID.
year_number number YES Academic year.
Example Request Payload (JSON)
{
  "form_name": "GNM 3rd Year Appraisal",
  "course_id": "c-gnm-01",
  "year_number": 3
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Created.
Response Payload Structure
Field Type Description
id string Created ID.
Example Success Response (JSON)
{
  "id": "cfg-03"
}
PATCH /api/admin/appraisal-form-configs/:id — Update Appraisal Configuration
🔒 Auth superadmin +1
API Purpose: Modifies appraisal form questions and rubric rubrics.

📍 Website Flow Placement

Appraisal Editor.

🔗 Dependencies & Prerequisites

Config ID.

⚖️ Validation & Business Rules

Superadmin only.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Config ID.
JSON Body Schema
Field Type Required Description
form_name string OPT Title.
Example Request Payload (JSON)
{
  "form_name": "Updated Form Name"
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/admin/appraisal-form-configs/:id/copy — Clone Appraisal Configuration to Another Year
🔒 Auth superadmin +1
API Purpose: Copies an appraisal configuration and questions to another academic year.

📍 Website Flow Placement

Clone Appraisal Template button.

🔗 Dependencies & Prerequisites

Source Config.

⚖️ Validation & Business Rules

Deep copies questions.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Source Config ID.
JSON Body Schema
Field Type Required Description
target_year_number number YES Target year number.
Example Request Payload (JSON)
{
  "target_year_number": 2
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
201 Cloned.
Response Payload Structure
Field Type Description
id string Cloned Config ID.
Example Success Response (JSON)
{
  "id": "cfg-02"
}
DELETE /api/admin/appraisal-form-configs/:id — Delete Appraisal Configuration
🔒 Auth superadmin +1
API Purpose: Deletes an unused appraisal template.

📍 Website Flow Placement

Delete appraisal template.

🔗 Dependencies & Prerequisites

Config ID.

⚖️ Validation & Business Rules

Checks for existing submissions.

📥 Request Specification

Required Headers
None required
Parameters (Path & Query)
Name In Type Required Description
id path string YES Config ID.
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Deleted.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
POST /api/admin/bulk-create-users — Bulk Create User Accounts
🔒 Auth superadmin +2
API Purpose: Dedicated batch creation utility for mass student imports.

📍 Website Flow Placement

Student Batch Importer.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

Enforces password hashing.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
users array YES User list.
Example Request Payload (JSON)
{
  "users": []
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Imported.
Example Success Response (JSON)
{
  "created": 0
}
POST /api/admin/bulk-update-profiles — Bulk Update User Profiles Roster
🔒 Auth superadmin +2
API Purpose: Dedicated batch update utility.

📍 Website Flow Placement

Profile batch updater.

🔗 Dependencies & Prerequisites

Admin role.

⚖️ Validation & Business Rules

Batch audit.

📥 Request Specification

Required Headers
Content-Type: application/json
JSON Body Schema
Field Type Required Description
profiles array YES Profile data.
Example Request Payload (JSON)
{
  "profiles": []
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Updated.
Example Success Response (JSON)
{
  "updated": 0
}
PATCH /api/admin/users/:id/payment-bypass — Toggle Student Payment Bypass Override
🔒 Auth superadmin +3
API Purpose: Grants or revokes a fee waiver for a student, bypassing Razorpay payment requirement.

📍 Website Flow Placement

Student Record -> 'Waive Subscription Fee' toggle.

🔗 Dependencies & Prerequisites

Student ID.

⚖️ Validation & Business Rules

Sets `payment_bypass` in `users`.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Student user ID.
JSON Body Schema
Field Type Required Description
bypass boolean YES True to waive fee, false to require payment.
Example Request Payload (JSON)
{
  "bypass": true
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Bypass flag set.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}
PATCH /api/admin/users/:id/enrollment-reset — Force Reset Student Enrollment State
🔒 Auth superadmin +5
API Purpose: Emergency correction endpoint for active year enrollment anomalies.

📍 Website Flow Placement

Troubleshooting panel.

🔗 Dependencies & Prerequisites

Student ID.

⚖️ Validation & Business Rules

Administrative audit.

📥 Request Specification

Required Headers
Content-Type: application/json
Parameters (Path & Query)
Name In Type Required Description
id path string YES Student ID.
JSON Body Schema
Field Type Required Description
year number YES Year (1, 2, 3).
Example Request Payload (JSON)
{
  "year": 1
}

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 Reset completed.
Response Payload Structure
Field Type Description
success boolean Outcome.
Example Success Response (JSON)
{
  "success": true
}

19. System Health & Infrastructure

Database connectivity probes, server uptime heartbeats, and cluster liveness checks.

2 APIs
GET /health — System Health & Uptime Probe
🌐 Public Public / Monitoring System
API Purpose: Validates backend server responsiveness and MySQL database connection pool health.

📍 Website Flow Placement

Load balancer liveness probe, Kubernetes health check, and internal watchdog.

🔗 Dependencies & Prerequisites

MySQL database pool.

⚖️ Validation & Business Rules

Runs fast `SELECT 1` ping.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 System operational and database connected.
500 Database unavailable.
Response Payload Structure
Field Type Description
status string 'ok' or 'error'.
database string 'connected' or 'unavailable'.
timestamp string (ISO Date) Server timestamp.
Example Success Response (JSON)
{
  "status": "ok",
  "database": "connected",
  "timestamp": "2026-09-29T10:15:00.000Z"
}
GET /api/health — API Subsystem Health Check
🌐 Public Public / Monitoring
API Purpose: Alternative path for automated API health monitoring.

📍 Website Flow Placement

Monitoring.

🔗 Dependencies & Prerequisites

Database pool.

⚖️ Validation & Business Rules

Same handler as `/health`.

📥 Request Specification

Required Headers
None required
No request body required for this method.

📤 Expected Response

Status Codes & Schema
Possible HTTP Status Codes
200 OK.
500 Database issue.
Response Payload Structure
Field Type Description
status string 'ok' or 'error'.
database string 'connected' or 'unavailable'.
timestamp string ISO timestamp.
Example Success Response (JSON)
{
  "status": "ok",
  "database": "connected",
  "timestamp": "2026-09-29T10:15:00.000Z"
}
Copied to clipboard!