Documentation - Institution Management System

Introduction

The Institution Management System provides a comprehensive REST API with 150+ endpoints covering Education, CRM, LMS, and ERP modules. All endpoints follow consistent patterns for CRUD operations, filtering, pagination, and error handling.

Base URL

https://your-domain.com/api

API Features

RESTful Design: Standard HTTP methods (GET, POST, PATCH, DELETE)
JWT Authentication: Secure token-based auth with configurable expiry
Role-Based Access: 23 roles with granular permissions and multi-role support
Single Institution: Designed for single-institution deployment
Consistent Responses: Standard JSON response formats
Error Handling: Detailed error messages with status codes

Authentication

The API uses JWT (JSON Web Tokens) for authentication. After login, include the access token in the Authorization header for all protected endpoints.

Header Format

Authorization: Bearer YOUR_ACCESS_TOKEN

Token Lifecycle

JWT Token: Configurable expiry (default: 7 days, set via JWT_EXPIRES_IN)
Cookie Storage: Frontend stores token as auth_token cookie
Payload: Contains id, email, role (primary role)

API Patterns

All API endpoints follow consistent patterns for standard CRUD operations. The system uses a single-institution design with a fixed companyId.

Standard Endpoints

GET /module/entity

List all records (with optional filtering)

GET /module/entity/:id

Get single record by ID

POST /module/entity

Create new record

PATCH /module/entity/:id

Update existing record

DELETE /module/entity/:id

Delete record

Notes

All endpoints return JSON responses
Lists are ordered by ID descending (newest first)
The system uses a single-institution design (companyId is fixed)

Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

Status Codes

200 OK: Successful GET, PATCH request
201 Created: Successful POST request
400 Bad Request: Invalid request data or validation error
401 Unauthorized: Missing or invalid authentication token
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server error

Error Response Format

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Login

Authenticate user and receive an access token.

POST /auth/login

Request Body

{
  "email": "[email protected]",
  "password": "password123"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "[email protected]",
    "name": "John Doe",
    "role": "INSTRUCTOR"
  }
}

Register

Create a new user account.

POST /auth/register

Request Body

{
  "email": "[email protected]",
  "password": "securePassword123",
  "name": "Jane Smith"
}

Response

{
  "id": 2,
  "email": "[email protected]",
  "name": "Jane Smith"
}

Current User

Get the currently authenticated user's profile.

GET /auth/me

Response

{
  "id": 1,
  "email": "[email protected]",
  "name": "Admin User",
  "role": "ADMINISTRATOR"
}

Change Password

Change the authenticated user's password.

POST /auth/change-password

Request Body

{
  "currentPassword": "oldPassword123",
  "newPassword": "newSecurePassword456"
}

Students

Manage student records in the Education module.

GET /education/students

List all students

POST /education/students

Create new student (auto-generates student code)

Create Student Example

{
  "studentName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "2005-06-15",
  "gender": "MALE",
  "studentEmail": "[email protected]",
  "phone": "+1234567890",
  "status": "APPLICANT"
}

Programs

Manage academic programs.

GET /education/programs

POST /education/programs

Example

{
  "programName": "Bachelor of Computer Science",
  "programAbbreviation": "BSc CS",
  "departmentId": 1,
  "programType": "BACHELOR",
  "duration": 4,
  "durationType": "DUR_YEARS",
  "totalCredits": 120,
  "totalCredits": 120
}

Courses

Manage courses in the Education module.

GET /education/courses

POST /education/courses

Enrollments

Manage program enrollments with transaction support for enrolled courses.

POST /education/program-enrollments

Example with Nested Courses

{
  "studentId": 1,
  "programId": 1,
  "academicYearId": 1,
  "academicTermId": 1,
  "enrollmentDate": "2024-09-01",
  "status": "ENR_ACTIVE",
  "enrolledCourses": [
    { "courseId": 101 },
    { "courseId": 102 }
  ]
}

Leads

CRM lead management with conversion capability.

GET /crm/leads

POST /crm/leads/:id/convert

Convert lead to contact and opportunity (atomic transaction)

Opportunities

Track enrollment opportunities through the sales pipeline.

GET /crm/opportunities

PATCH /crm/opportunities/:id

Update opportunity status and probability

LMS Courses

Manage online courses with chapters, lessons, and enrollments.

GET /lms/courses

List all courses (with status, pricing, category)

POST /lms/courses

Create a new course

GET /lms/courses/:id

Get course with chapters and enrollments

POST /lms/enrollments

Enroll student in LMS course with progress tracking

Course Packs

Manage bundled course packages with publish/unpublish control and savings calculation.

GET /lms/course-packs

List all course packs (admin — includes unpublished)

GET /lms/course-packs/published?companyId=1

List published course packs (public endpoint)

POST /lms/course-packs

Create a new course pack with courses and pricing

PATCH /lms/course-packs/:id

Update course pack (including publish/unpublish via isPublished field)

GET /lms/course-packs/:id/savings

Calculate savings vs individual course purchase

DELETE /lms/course-packs/:id

Delete course pack (blocked if successful payments exist)

Mark Students Complete (Admin/Instructor Bypass)

Allows administrators and course instructors (owners or mentors) to bypass the normal lesson-by-lesson completion flow and mark enrolled students as fully completed. This marks all lessons, creates quiz/assignment submissions with full scores, sets enrollment to 100%, and auto-issues a certificate if a template is configured.

POST /lms/courses/:id/mark-complete

Mark one or more enrolled students as fully completed

Permission: lms:course:update

Request Body

{
  "studentIds": [1, 2, 3]
}

What It Does

Marks all course lessons as LLP_COMPLETED for each student
Creates quiz submissions with 100% score / LQS_GRADED for unanswered quizzes
Creates assignment submissions with full score / LAS_GRADED for unsubmitted assignments
Sets enrollment progress to 100% and status to LE_COMPLETED
Auto-issues a certificate if a certificate template is linked to the course

Response

{
  "courseId": 1,
  "results": [
    { "studentId": 1, "status": "completed", "message": "Marked as completed" },
    { "studentId": 2, "status": "skipped", "message": "Already completed with certificate" },
    { "studentId": 3, "status": "skipped", "message": "Not enrolled in this course" }
  ]
}

Access Control

Administrators / System Managers: Full access to all courses
LMS Managers: Full access to all courses
Instructors: Only courses they own (as instructor) or mentor (as collaborator)

Chapters & Lessons

Both chapters and lessons support attaching quizzes and assignments directly. Use chapter-level for module-end assessments; use lesson-level for in-lesson assessments.

GET /lms/chapters/:id/content

Chapter with lessons (each including their quizzes & assignments), chapter quizzes, and chapter assignments

POST /lms/chapters/:id/quizzes

Attach a quiz to a chapter — body: { lmsQuizId, sortOrder? }

POST /lms/chapters/:id/assignments

Attach an assignment to a chapter — body: { lmsAssignmentId, sortOrder? }

PATCH /lms/chapters/:id/reorder

Reorder lessons, quizzes, and assignments within a chapter — body: { items: [{ type, id, sortOrder }] }

GET /lms/lessons/:id/content

Lesson with its own quizzes and assignments

POST /lms/lessons/:id/quizzes

Attach a quiz to a lesson — body: { lmsQuizId, sortOrder? }

POST /lms/lessons/:id/assignments

Attach an assignment to a lesson — body: { lmsAssignmentId, sortOrder? }

PATCH /lms/lessons/:id/reorder

Reorder quizzes and assignments within a lesson — body: { items: [{ type, id, sortOrder }] }

Quizzes

Quiz management with automatic grading for objective questions. Quizzes can be linked to chapters and/or lessons.

GET /lms/quizzes/:id/associations

Get all chapters & lessons this quiz is linked to

POST /lms/quizzes/:id/chapters

Link quiz to a chapter — body: { lmsChapterId, sortOrder? }

POST /lms/quizzes/:id/lessons

Link quiz to a lesson — body: { lmsLessonId, sortOrder? }

POST /lms/quiz-submissions

Submit quiz with auto-grading

Assignments

Assignment submission and grading with rubric support. Assignments can be linked to chapters and/or lessons.

GET /lms/assignments/:id/associations

Get all chapters & lessons this assignment is linked to

POST /lms/assignments/:id/chapters

Link assignment to a chapter — body: { lmsChapterId, sortOrder? }

POST /lms/assignments/:id/lessons

Link assignment to a lesson — body: { lmsLessonId, sortOrder? }

POST /lms/assignment-submissions

Submit assignment

PATCH /lms/assignment-submissions/:id

Grade submission with feedback

Rubrics

Rubric management for structured grading criteria. Rubrics can be linked to assignments, quizzes, and education assessment plans.

GET /lms/rubrics

List all rubrics

POST /lms/rubrics

Create rubric with nested criteria and levels

GET /lms/rubrics/:id

Get rubric with criteria and levels

PATCH /lms/rubrics/:id

Update rubric (with nested criteria/levels)

DELETE /lms/rubrics/:id

Delete rubric

Create Rubric Example

{
  "title": "Essay Rubric",
  "description": "Grading rubric for essay assignments",
  "criteria": [
    {
      "name": "Content",
      "weight": 40,
      "levels": [
        { "label": "Excellent", "points": 5, "description": "Thorough and insightful" },
        { "label": "Good", "points": 3, "description": "Adequate coverage" },
        { "label": "Needs Work", "points": 1, "description": "Incomplete or superficial" }
      ]
    }
  ]
}

LMS Certificates

Certificate management with configurable issuance modes per course.

GET /lms/certificates

List issued certificates

POST /lms/certificates

Issue certificate (standard)

POST /lms/certificates/issue

Manually issue certificate for a completed enrollment (CERT_MANUAL mode)

Issuance Modes

CERT_AUTO: Certificate auto-issued on course completion
CERT_MANUAL: Staff issues via POST /lms/certificates/issue with { enrollmentId }
CERT_DISABLED: No certificates for this course

Manual Issue Request

{
  "enrollmentId": 42
}

Accounting

ERP accounting endpoints for journal entries, invoices, and payments.

POST /erp/journal-entries

Create journal entry with debit/credit validation

POST /erp/sales-invoices

Create sales invoice with auto-calculation

POST /erp/payment-entries

Record payment with invoice allocation

HR & Payroll

Employee management and payroll processing.

POST /erp/employees

Create employee with auto-generated employee code

POST /erp/payroll-entries

Batch process payroll for multiple employees

Inventory

Stock management with multi-warehouse support.

POST /erp/stock-entries

Record stock movements (receipt, issue, transfer)

GET /erp/stock-ledger

Query stock ledger for audit trail

Reports & Dashboards

Dashboard analytics and downloadable reports for all modules.

GET /reports/education/*

Education dashboard stats and reports

GET /reports/crm/*

CRM dashboard (leads, conversions, pipeline)

GET /reports/lms/*

LMS dashboard and reports (enrollments, progress, completions)

GET /reports/erp-finance/*

Financial dashboard and reports (revenue, expenses, invoices)

GET /reports/erp-hr/*

HR dashboard (headcount, attendance, leave)

Audit Logs

Query audit trail of all mutations (create, update, delete) across the system. Admin-only access.

GET /audit-logs

List audit log entries with filtering

Email Settings

Global SMTP email configuration (singleton). Supports per-category notification toggles.

GET /email-settings

Get current email settings (password masked)

PUT /email-settings

Upsert email settings (AES-256-GCM encrypted password)

POST /email-settings/test

Send SMTP test email

PisoPay

Philippine payment gateway integration for online fee payments.

POST /pisopay/checkout

Create a payment checkout session

POST /pisopay/callback

Payment callback handler (webhook)

Website Builder

GrapesJS-based page builder for institutional websites.

GET /website-builder/pages

List all pages

POST /website-builder/pages

Create a new page with HTML/CSS/JS content

PATCH /website-builder/pages/:id

Update page content and settings

Introduction

Base URL

https://your-domain.com/api

API Features

RESTful Design: Standard HTTP methods (GET, POST, PATCH, DELETE)
JWT Authentication: Secure token-based auth with configurable expiry
Role-Based Access: 23 roles with granular permissions and multi-role support
Single Institution: Designed for single-institution deployment
Consistent Responses: Standard JSON response formats
Error Handling: Detailed error messages with status codes

Authentication

The API uses JWT (JSON Web Tokens) for authentication. After login, include the access token in the Authorization header for all protected endpoints.

Header Format

Authorization: Bearer YOUR_ACCESS_TOKEN

Token Lifecycle

JWT Token: Configurable expiry (default: 7 days, set via JWT_EXPIRES_IN)
Cookie Storage: Frontend stores token as auth_token cookie
Payload: Contains id, email, role (primary role)

API Patterns

All API endpoints follow consistent patterns for standard CRUD operations. The system uses a single-institution design with a fixed companyId.

Standard Endpoints

GET /module/entity

List all records (with optional filtering)

GET /module/entity/:id

Get single record by ID

POST /module/entity

Create new record

PATCH /module/entity/:id

Update existing record

DELETE /module/entity/:id

Delete record

Notes

All endpoints return JSON responses
Lists are ordered by ID descending (newest first)
The system uses a single-institution design (companyId is fixed)

Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

Status Codes

200 OK: Successful GET, PATCH request
201 Created: Successful POST request
400 Bad Request: Invalid request data or validation error
401 Unauthorized: Missing or invalid authentication token
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server error

Error Response Format

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Login

Authenticate user and receive an access token.

POST /auth/login

Request Body

{
  "email": "[email protected]",
  "password": "password123"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "[email protected]",
    "name": "John Doe",
    "role": "INSTRUCTOR"
  }
}

Register

Create a new user account.

POST /auth/register

Request Body

{
  "email": "[email protected]",
  "password": "securePassword123",
  "name": "Jane Smith"
}

Response

{
  "id": 2,
  "email": "[email protected]",
  "name": "Jane Smith"
}

Current User

Get the currently authenticated user's profile.

GET /auth/me

Response

{
  "id": 1,
  "email": "[email protected]",
  "name": "Admin User",
  "role": "ADMINISTRATOR"
}

Change Password

Change the authenticated user's password.

POST /auth/change-password

Request Body

{
  "currentPassword": "oldPassword123",
  "newPassword": "newSecurePassword456"
}

Students

Manage student records in the Education module.

GET /education/students

List all students

POST /education/students

Create new student (auto-generates student code)

Create Student Example

{
  "studentName": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "dateOfBirth": "2005-06-15",
  "gender": "MALE",
  "studentEmail": "[email protected]",
  "phone": "+1234567890",
  "status": "APPLICANT"
}

Programs

Manage academic programs.

GET /education/programs

POST /education/programs

Example

{
  "programName": "Bachelor of Computer Science",
  "programAbbreviation": "BSc CS",
  "departmentId": 1,
  "programType": "BACHELOR",
  "duration": 4,
  "durationType": "DUR_YEARS",
  "totalCredits": 120,
  "totalCredits": 120
}

Courses

Manage courses in the Education module.

GET /education/courses

POST /education/courses

Enrollments

Manage program enrollments with transaction support for enrolled courses.

POST /education/program-enrollments

Example with Nested Courses

{
  "studentId": 1,
  "programId": 1,
  "academicYearId": 1,
  "academicTermId": 1,
  "enrollmentDate": "2024-09-01",
  "status": "ENR_ACTIVE",
  "enrolledCourses": [
    { "courseId": 101 },
    { "courseId": 102 }
  ]
}

Leads

CRM lead management with conversion capability.

GET /crm/leads

POST /crm/leads/:id/convert

Convert lead to contact and opportunity (atomic transaction)

Opportunities

Track enrollment opportunities through the sales pipeline.

GET /crm/opportunities

PATCH /crm/opportunities/:id

Update opportunity status and probability

LMS Courses

Manage online courses with chapters, lessons, and enrollments.

GET /lms/courses

List all courses (with status, pricing, category)

POST /lms/courses

Create a new course

GET /lms/courses/:id

Get course with chapters and enrollments

POST /lms/enrollments

Enroll student in LMS course with progress tracking

Course Packs

Manage bundled course packages with publish/unpublish control and savings calculation.

GET /lms/course-packs

List all course packs (admin — includes unpublished)

GET /lms/course-packs/published?companyId=1

List published course packs (public endpoint)

POST /lms/course-packs

Create a new course pack with courses and pricing

PATCH /lms/course-packs/:id

Update course pack (including publish/unpublish via isPublished field)

GET /lms/course-packs/:id/savings

Calculate savings vs individual course purchase

DELETE /lms/course-packs/:id

Delete course pack (blocked if successful payments exist)

Mark Students Complete (Admin/Instructor Bypass)

POST /lms/courses/:id/mark-complete

Mark one or more enrolled students as fully completed

Permission: lms:course:update

Request Body

{
  "studentIds": [1, 2, 3]
}

What It Does

Marks all course lessons as LLP_COMPLETED for each student
Creates quiz submissions with 100% score / LQS_GRADED for unanswered quizzes
Creates assignment submissions with full score / LAS_GRADED for unsubmitted assignments
Sets enrollment progress to 100% and status to LE_COMPLETED
Auto-issues a certificate if a certificate template is linked to the course

Response

{
  "courseId": 1,
  "results": [
    { "studentId": 1, "status": "completed", "message": "Marked as completed" },
    { "studentId": 2, "status": "skipped", "message": "Already completed with certificate" },
    { "studentId": 3, "status": "skipped", "message": "Not enrolled in this course" }
  ]
}

Access Control

Administrators / System Managers: Full access to all courses
LMS Managers: Full access to all courses
Instructors: Only courses they own (as instructor) or mentor (as collaborator)

Chapters & Lessons

Both chapters and lessons support attaching quizzes and assignments directly. Use chapter-level for module-end assessments; use lesson-level for in-lesson assessments.

GET /lms/chapters/:id/content

Chapter with lessons (each including their quizzes & assignments), chapter quizzes, and chapter assignments

POST /lms/chapters/:id/quizzes

Attach a quiz to a chapter — body: { lmsQuizId, sortOrder? }

POST /lms/chapters/:id/assignments

Attach an assignment to a chapter — body: { lmsAssignmentId, sortOrder? }

PATCH /lms/chapters/:id/reorder

Reorder lessons, quizzes, and assignments within a chapter — body: { items: [{ type, id, sortOrder }] }

GET /lms/lessons/:id/content

Lesson with its own quizzes and assignments

POST /lms/lessons/:id/quizzes

Attach a quiz to a lesson — body: { lmsQuizId, sortOrder? }

POST /lms/lessons/:id/assignments

Attach an assignment to a lesson — body: { lmsAssignmentId, sortOrder? }

PATCH /lms/lessons/:id/reorder

Reorder quizzes and assignments within a lesson — body: { items: [{ type, id, sortOrder }] }

Quizzes

Quiz management with automatic grading for objective questions. Quizzes can be linked to chapters and/or lessons.

GET /lms/quizzes/:id/associations

Get all chapters & lessons this quiz is linked to

POST /lms/quizzes/:id/chapters

Link quiz to a chapter — body: { lmsChapterId, sortOrder? }

POST /lms/quizzes/:id/lessons

Link quiz to a lesson — body: { lmsLessonId, sortOrder? }

POST /lms/quiz-submissions

Submit quiz with auto-grading

Assignments

Assignment submission and grading with rubric support. Assignments can be linked to chapters and/or lessons.

GET /lms/assignments/:id/associations

Get all chapters & lessons this assignment is linked to

POST /lms/assignments/:id/chapters

Link assignment to a chapter — body: { lmsChapterId, sortOrder? }

POST /lms/assignments/:id/lessons

Link assignment to a lesson — body: { lmsLessonId, sortOrder? }

POST /lms/assignment-submissions

Submit assignment

PATCH /lms/assignment-submissions/:id

Grade submission with feedback

Rubrics

Rubric management for structured grading criteria. Rubrics can be linked to assignments, quizzes, and education assessment plans.

GET /lms/rubrics

List all rubrics

POST /lms/rubrics

Create rubric with nested criteria and levels

GET /lms/rubrics/:id

Get rubric with criteria and levels

PATCH /lms/rubrics/:id

Update rubric (with nested criteria/levels)

DELETE /lms/rubrics/:id

Delete rubric

Create Rubric Example

{
  "title": "Essay Rubric",
  "description": "Grading rubric for essay assignments",
  "criteria": [
    {
      "name": "Content",
      "weight": 40,
      "levels": [
        { "label": "Excellent", "points": 5, "description": "Thorough and insightful" },
        { "label": "Good", "points": 3, "description": "Adequate coverage" },
        { "label": "Needs Work", "points": 1, "description": "Incomplete or superficial" }
      ]
    }
  ]
}

LMS Certificates

Certificate management with configurable issuance modes per course.

GET /lms/certificates

List issued certificates

POST /lms/certificates

Issue certificate (standard)

POST /lms/certificates/issue

Manually issue certificate for a completed enrollment (CERT_MANUAL mode)

Issuance Modes

CERT_AUTO: Certificate auto-issued on course completion
CERT_MANUAL: Staff issues via POST /lms/certificates/issue with { enrollmentId }
CERT_DISABLED: No certificates for this course

Manual Issue Request

{
  "enrollmentId": 42
}

Accounting

ERP accounting endpoints for journal entries, invoices, and payments.

POST /erp/journal-entries

Create journal entry with debit/credit validation

POST /erp/sales-invoices

Create sales invoice with auto-calculation

POST /erp/payment-entries

Record payment with invoice allocation

HR & Payroll

Employee management and payroll processing.

POST /erp/employees

Create employee with auto-generated employee code

POST /erp/payroll-entries

Batch process payroll for multiple employees

Inventory

Stock management with multi-warehouse support.

POST /erp/stock-entries

Record stock movements (receipt, issue, transfer)

GET /erp/stock-ledger

Query stock ledger for audit trail

Reports & Dashboards

Dashboard analytics and downloadable reports for all modules.

GET /reports/education/*

Education dashboard stats and reports

GET /reports/crm/*

CRM dashboard (leads, conversions, pipeline)

GET /reports/lms/*

LMS dashboard and reports (enrollments, progress, completions)

GET /reports/erp-finance/*

Financial dashboard and reports (revenue, expenses, invoices)

GET /reports/erp-hr/*

HR dashboard (headcount, attendance, leave)

Audit Logs

Query audit trail of all mutations (create, update, delete) across the system. Admin-only access.

GET /audit-logs

List audit log entries with filtering

Email Settings

Global SMTP email configuration (singleton). Supports per-category notification toggles.

GET /email-settings

Get current email settings (password masked)

PUT /email-settings

Upsert email settings (AES-256-GCM encrypted password)

POST /email-settings/test

Send SMTP test email

PisoPay

Philippine payment gateway integration for online fee payments.

POST /pisopay/checkout

Create a payment checkout session

POST /pisopay/callback

Payment callback handler (webhook)

Website Builder

GrapesJS-based page builder for institutional websites.

GET /website-builder/pages

List all pages

POST /website-builder/pages

Create a new page with HTML/CSS/JS content

PATCH /website-builder/pages/:id

Update page content and settings