AVT School ERP API Documentation

Complete School Management System - Multi-Tenant SaaS Platform

Auth Complete All Modules Active v1.0.0

Introduction

The AVT School ERP API provides a comprehensive REST API for managing all aspects of school operations. The system is designed as a multi-tenant SaaS platform where each school operates on their own subdomain.

Base URL

Development: http://localhost:5012/api/v1
Production:  https://school.avterp.com/api/v1

Response Format

All responses follow a consistent JSON structure:

{
  "ok": true,
  "data": { ... }
}

// Error response
{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message"
  }
}

Request Headers

Header Required Description
Content-Type Yes application/json
Authorization For protected routes Bearer <access_token>
x-tenant-id For multi-tenant routes Tenant identifier (school subdomain)

Quick Navigation

Authentication
Login, Refresh, Logout
Students
Profiles, Certificates
Attendance
Daily, Period-wise
Fees
Invoices, Payments
Exams
Marks, Report Cards
Reports
Dashboard, Exports

Authentication

The API uses JWT-based authentication with access and refresh tokens.

Token Lifecycle: Access tokens expire in 15 minutes. Use the refresh token to obtain new access tokens without re-authentication.

Token Flow

  1. Login with credentials to receive access + refresh tokens
  2. Include access token in Authorization header for API calls
  3. When access token expires, use refresh endpoint to get new tokens
  4. On logout, revoke the refresh token
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

User Roles & Permissions

The system supports 7 user roles with different permission levels:

Super Admin

Platform Owner

Full access to all features across all tenants. Can manage subscriptions and plans.
School Admin

School Administrator

Full access within school: masters, students, fees, attendance, exams, reports, notifications.
Principal

School Principal

Read access to masters, attendance, exams. Can manage exam configs and notifications.
Teacher

Teaching Staff

Can mark attendance, create homework, enter marks, view timetable and reports.
Accountant

Finance Staff

Full access to fees module, can generate invoices, receipts, and financial reports.
Parent

Parent/Guardian

Read access to child's profile, attendance, marks, and fee dues.
Student

Student User

Read access to own profile, timetable, homework, and marks.

Error Codes

HTTP Status Error Code Description
400 INVALID_INPUT Request validation failed - check required fields
401 UNAUTHORIZED Missing or invalid bearer token
401 INVALID_TOKEN Token is expired or malformed
401 INVALID_REFRESH_TOKEN Refresh token is invalid or revoked
403 FORBIDDEN User lacks required permission
403 TENANT_MISMATCH Token tenant doesn't match request tenant
403 MODULE_DISABLED Module not enabled for tenant subscription
404 NOT_FOUND Requested resource not found
409 DUPLICATE Resource already exists
429 RATE_LIMIT Too many requests - try again later
500 INTERNAL_ERROR Server error - contact support

Auth API

POST /auth/login

Authenticate user and receive access + refresh tokens

Request Body

{
  "username": "admin@school.com",
  "tenantId": "demo-school",
  "role": "school_admin"
}

Parameters

FieldTypeRequiredDescription
username string Yes User email or username (3-64 chars)
tenantId string Yes School tenant identifier
role string Yes One of: super_admin, school_admin, principal, teacher, accountant, parent, student

Response (200 OK)

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "abc123.xyz789",
    "user": {
      "userId": "admin@school.com",
      "tenantId": "demo-school",
      "role": "school_admin",
      "permissions": ["masters:read", "masters:write", "student:read", ...]
    }
  }
}
POST /auth/refresh

Exchange refresh token for new access token

Request Body

{
  "refreshToken": "abc123.xyz789"
}

Response (200 OK)

{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "new123.token789",
    "user": { ... }
  }
}
POST /auth/logout

Revoke refresh token and end session

Auth Required: Bearer Token

Request Body

{
  "refreshToken": "abc123.xyz789"
}

Response (200 OK)

{
  "ok": true,
  "data": { "success": true }
}
GET /auth/me

Get current authenticated user information

Auth Required: Bearer Token

Response (200 OK)

{
  "ok": true,
  "data": {
    "userId": "admin@school.com",
    "tenantId": "demo-school",
    "role": "school_admin",
    "permissions": ["masters:read", "masters:write", ...]
  }
}

Masters API

Manage core master data: academic years, classes, sections, and subjects.

Academic Years

GET /masters/academic-years

List all academic years for the tenant

Permission: masters:read

POST /masters/academic-years

Create a new academic year

Permission: masters:write

Request Body

{
  "code": "2025-26",
  "name": "Academic Year 2025-26",
  "startDate": "2025-04-01",
  "endDate": "2026-03-31",
  "isCurrent": true
}

Classes

GET /masters/classes

List all classes

POST /masters/classes

Create a new class

Request Body

{
  "code": "CLASS-10",
  "name": "Class 10",
  "gradeLevel": 10,
  "displayOrder": 10
}

Sections

GET /masters/sections

List all sections

POST /masters/sections

Create a new section

Request Body

{
  "code": "SEC-A",
  "name": "Section A",
  "classId": "CLASS-10",
  "capacity": 40
}

Subjects

GET /masters/subjects

List all subjects

POST /masters/subjects

Create a new subject

Request Body

{
  "code": "MATH-10",
  "name": "Mathematics",
  "classId": "CLASS-10",
  "subjectType": "core",
  "credits": 5
}

Bulk Import/Export

GET /masters/export/classes.csv

Export classes as CSV file

POST /masters/import/classes

Bulk import classes from CSV data

Capabilities API

Check tenant subscription and module availability.

GET /tenant/capabilities

Get tenant's enabled modules and limits

Response

{
  "ok": true,
  "data": {
    "tenantId": "demo-school",
    "subscriptionStatus": "active",
    "modules": {
      "fees": { "enabled": true, "reason": "plan_included" },
      "hostel": { "enabled": false, "reason": "not_in_plan" }
    },
    "limits": {
      "studentsMax": 1500,
      "studentsUsed": 847,
      "storageGb": 50,
      "storageUsedGb": 12.5
    }
  }
}
GET /tenant/subscription

Get detailed subscription information

Students API

Manage student profiles, certificates, and lifecycle.

GET /students

List all students

Permission: student:read

GET /students/:id

Get student details by ID

POST /students

Create a new student (manual entry)

Permission: student:write

Request Body

{
  "fullName": "John Smith",
  "dateOfBirth": "2010-05-15",
  "gender": "male",
  "classId": "CLASS-10",
  "sectionId": "SEC-A",
  "academicYearId": "2025-26",
  "guardianName": "Robert Smith",
  "guardianPhone": "+919876543210",
  "guardianEmail": "robert@example.com"
}
POST /students/:id/promote

Promote student to next class

POST /students/:id/exit

Mark student exit/transfer

Certificates

POST /students/:id/certificates

Issue a certificate (TC, Bonafide, Character, Fee Clearance)

Request Body

{
  "type": "bonafide",
  "remarks": "Issued for passport application"
}
GET /students/:id/certificates/:type/pdf

Download certificate as PDF

Admissions API

Handle admission inquiries and enrollment workflow.

GET /admissions/inquiries

List all admission inquiries

POST /admissions/inquiries

Create a new admission inquiry

Request Body

{
  "studentName": "Jane Doe",
  "dateOfBirth": "2012-08-20",
  "applyingForClass": "CLASS-5",
  "guardianName": "John Doe",
  "guardianPhone": "+919876543210",
  "guardianEmail": "john@example.com",
  "previousSchool": "ABC Public School"
}
PATCH /admissions/inquiries/:id/status

Update inquiry status (new → in_review → approved/rejected)

Request Body

{
  "status": "approved",
  "remarks": "All documents verified"
}

Attendance API

Manage daily and period-wise attendance.

GET /attendance/classes/:classId/daily

Get daily attendance for a class

Query Params: date (YYYY-MM-DD), sectionId

POST /attendance/classes/:classId/mark

Mark daily attendance for a class

Permission: attendance:write

Request Body

{
  "date": "2026-02-12",
  "sectionId": "SEC-A",
  "entries": [
    { "studentId": "STU001", "status": "present" },
    { "studentId": "STU002", "status": "absent", "reason": "sick" },
    { "studentId": "STU003", "status": "late", "remarks": "10 mins late" }
  ]
}
GET /attendance/students/:studentId/summary

Get attendance summary for a student

Response

{
  "ok": true,
  "data": {
    "studentId": "STU001",
    "totalDays": 180,
    "presentDays": 165,
    "absentDays": 10,
    "lateDays": 5,
    "attendancePercentage": 91.67
  }
}
GET /attendance/classes/:classId/analytics

Get attendance analytics for a class

Timetable API

GET /timetable/classes/:classId/entries

Get timetable entries for a class

POST /timetable/classes/:classId/entries

Create a timetable entry

Request Body

{
  "sectionId": "SEC-A",
  "dayOfWeek": 1,
  "periodNumber": 1,
  "subjectId": "MATH-10",
  "teacherId": "TCH001",
  "startTime": "08:00",
  "endTime": "08:45"
}

Exams API

Manage exams, marks, report cards, and re-evaluations.

GET /exams

List all exam definitions

POST /exams

Create a new exam

Request Body

{
  "name": "Mid-Term Examination 2025-26",
  "examType": "midterm",
  "academicYearId": "2025-26",
  "startDate": "2025-09-15",
  "endDate": "2025-09-25",
  "classIds": ["CLASS-9", "CLASS-10"],
  "maxMarks": 100,
  "passingMarks": 35
}
POST /exams/:examId/marks

Enter/update marks for students

Permission: exams:write

Request Body

{
  "subjectId": "MATH-10",
  "entries": [
    { "studentId": "STU001", "marksObtained": 85, "remarks": "Excellent" },
    { "studentId": "STU002", "marksObtained": 72, "remarks": "Good" }
  ]
}
POST /exams/:examId/publish

Publish exam results

GET /report-cards/students/:studentId

Get student's report card

Re-evaluation

POST /exams/:examId/re-evaluations

Request re-evaluation

Fees API

Manage fee structure, invoices, payments, and concessions.

GET /fees/summary

Get fees summary (totals collected, pending)

Permission: fees:read

Fee Heads & Plans

GET /fees/heads

List all fee heads (Tuition, Transport, etc.)

POST /fees/heads

Create a fee head

Request Body

{
  "code": "TUITION",
  "name": "Tuition Fee",
  "description": "Monthly tuition charges",
  "isRecurring": true,
  "frequency": "monthly"
}
GET /fees/plans

List fee plans

POST /fees/plans

Create a fee plan

Invoices & Receipts

GET /fees/invoices

List all invoices

POST /fees/invoices

Create a manual invoice

POST /fees/receipts

Record payment receipt

Request Body

{
  "invoiceId": "INV-2026-001",
  "amount": 15000,
  "paymentMode": "online",
  "transactionId": "TXN123456",
  "paymentDate": "2026-02-12"
}
GET /fees/outstanding

List outstanding (unpaid) invoices

GET /fees/ledger/:studentId

Get fee ledger for a student

Adjustments

POST /fees/adjustments

Apply concession, scholarship, or penalty

Request Body

{
  "invoiceId": "INV-2026-001",
  "type": "concession",
  "amount": 2000,
  "reason": "Sibling discount"
}

Payments API

Online payment integration with Razorpay.

POST /payments/orders

Create payment order

Request Body

{
  "invoiceId": "INV-2026-001",
  "amount": 15000,
  "currency": "INR"
}

Response

{
  "ok": true,
  "data": {
    "orderId": "order_xyz123",
    "amount": 1500000,
    "currency": "INR",
    "key": "rzp_test_xxxxx"
  }
}
POST /payments/webhook/razorpay/verify

Verify Razorpay payment signature

HR & Payroll API

Staff Management

GET /hr/staff

List all staff members

POST /hr/staff

Create staff member

Leave Management

GET /hr/leave-requests

List leave requests

POST /hr/leave-requests

Submit leave request

Payroll

GET /payroll/runs

List payroll runs

POST /payroll/runs

Generate payroll run

GET /payroll/payslips/:id

Get payslip details

Transport API

GET /transport/routes

List transport routes

POST /transport/routes

Create transport route

Request Body

{
  "code": "ROUTE-1",
  "name": "North Zone Route",
  "vehicleNumber": "KA-01-1234",
  "driverName": "Ram Kumar",
  "driverPhone": "+919876543210"
}
POST /transport/routes/:routeId/stops

Add stop to route

Library API

GET /library/books

List library books with availability

POST /library/books

Add a book to library

POST /library/issues

Issue book to member

POST /library/issues/:id/return

Return an issued book

Inventory API

GET /inventory/items

List inventory items

POST /inventory/items

Create inventory item

POST /inventory/items/:itemId/movements

Record inventory movement (in/out/adjustment)

Notifications API

GET /notifications/history

List notification history

POST /notifications/announce

Send announcement

Permission: notifications:write

Request Body

{
  "title": "School Holiday Notice",
  "message": "School will remain closed on 26th January for Republic Day.",
  "targetType": "all",
  "channels": ["push", "sms", "email"]
}

Reports API

GET /reports/dashboard

Get dashboard summary

Response

{
  "ok": true,
  "data": {
    "totalStudents": 847,
    "totalStaff": 52,
    "todayAttendance": 92.5,
    "feeCollectionThisMonth": 1250000,
    "pendingFees": 450000,
    "upcomingEvents": 3
  }
}
GET /reports/dashboard/role-wise

Get role-specific dashboard data

CSV Exports

GET /reports/export/fees-outstanding.csv

Export outstanding fees as CSV

GET /reports/export/attendance-daily.csv

Export daily attendance as CSV

Scheduled Reports

POST /reports/schedules

Create scheduled report

Mobile API

GET /mobile/bootstrap

Get mobile app bootstrap data

Response

{
  "ok": true,
  "data": {
    "user": {
      "userId": "parent@example.com",
      "role": "parent",
      "children": ["STU001", "STU002"]
    },
    "capabilities": {
      "modules": { "fees": true, "attendance": true }
    },
    "quickStats": {
      "unreadNotifications": 3,
      "pendingFees": 25000,
      "todayAttendance": "present"
    }
  }
}

Testing Examples

cURL Examples

Health Check

curl http://localhost:5012/api/v1/health

Login

curl -X POST http://localhost:5012/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: demo-school" \
  -d '{"username":"admin@school.com","tenantId":"demo-school","role":"school_admin"}'

List Students (with auth)

curl http://localhost:5012/api/v1/students \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant-id: demo-school"

Mark Attendance

curl -X POST http://localhost:5012/api/v1/attendance/classes/CLASS-10/mark \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-tenant-id: demo-school" \
  -d '{
    "date": "2026-02-12",
    "sectionId": "SEC-A",
    "entries": [
      {"studentId": "STU001", "status": "present"},
      {"studentId": "STU002", "status": "absent", "reason": "sick"}
    ]
  }'

© 2026 Avuetech Solutions. All rights reserved.

www.avuetech.com | support@avuetech.com