Attendance API

The Attendance module tracks student attendance for classes and courses.

Model

{
  "id": "uuid",
  "student_id": "student-uuid",
  "student": { "id": "...", "name": "John Doe", "code": "STD001" },
  "class_id": "class-uuid",
  "class": { "id": "...", "name": "Class 10A" },
  "course_id": "course-uuid",
  "course": { "id": "...", "name": "Mathematics" },
  "attendance_date": "2024-01-15",
  "status": "Present",
  "type": "Class",
  "description": "On time",
  "academic_session_id": "session-uuid",
  "timetables_detail_id": "period-uuid",
  "team_id": "team-uuid",
  "created_at": "2024-01-15T08:00:00Z"
}

Status Values

Status	Description
`Present`	Student was present
`Late`	Student arrived late
`AbsentRequest`	Absent with prior notification
`AbsentNoRequest`	Absent without notification

!!! tip “Frontend Mapping” Frontend can use absent_with_leave (maps to AbsentRequest) and absent_without_leave (maps to AbsentNoRequest)

Attendance Types

Type	Description
`Class`	Homeroom class attendance
`Course`	Subject course attendance
`Exam`	Exam attendance
`Event`	Event attendance

Endpoints

Standard CRUD Endpoints

Method	Endpoint	Description
POST	`/api/attendances`	Create single attendance
POST	`/api/attendances/list`	List with pagination
GET	`/api/attendances/:id`	Get by ID
PUT	`/api/attendances/:id`	Update attendance
DELETE	`/api/attendances/:id`	Delete attendance
POST	`/api/attendances/export`	Export to Excel

Bulk Class Attendance

Create/update attendance for all students in a class.

Endpoint: POST /api/attendances/class-attendance

Request:

{
  "date": "2024-01-15",
  "class_id": "class-uuid",
  "attendances": [
    {
      "student_id": "student-uuid-1",
      "status": "Present",
      "comment": "On time"
    },
    {
      "student_id": "student-uuid-2",
      "status": "Late",
      "comment": "Arrived 10 minutes late"
    },
    {
      "student_id": "student-uuid-3",
      "status": "absent_with_leave",
      "comment": "Sick leave"
    }
  ]
}

Response:

{
  "success": true,
  "message": "Attendance records created successfully",
  "data": {
    "created": 3,
    "records": [...],
    "duplicates_handled": 0
  }
}

Bulk Course Attendance

Create/update attendance for students in a course.

Endpoint: POST /api/attendances/course-attendance

Request:

{
  "date": "2024-01-15",
  "course_id": "course-uuid",
  "timetables_detail_id": "period-uuid",
  "attendances": [
    {
      "student_id": "student-uuid-1",
      "status": "Present"
    }
  ]
}

Get Student Attendance Details

Endpoint: GET /api/attendances/student/:student_id

Query Parameters:

start_date - Start of date range (YYYY-MM-DD)
end_date - End of date range (YYYY-MM-DD)
type - Filter by attendance type

Response:

{
  "success": true,
  "data": {
    "student": { "id": "...", "name": "John Doe" },
    "summary": {
      "total_days": 100,
      "present": 90,
      "late": 5,
      "absent_request": 3,
      "absent_no_request": 2,
      "attendance_rate": 95.0
    },
    "records": [...]
  }
}

Get Attendance Statuses

Get configured attendance statuses for the team.

Endpoint: GET /api/attendances/statuses

Response:

{
  "success": true,
  "data": [
    {"code": "Present", "name": "Present", "color": "#4CAF50"},
    {"code": "Late", "name": "Late", "color": "#FF9800"},
    {"code": "AbsentRequest", "name": "Absent (With Leave)", "color": "#2196F3"},
    {"code": "AbsentNoRequest", "name": "Absent (No Leave)", "color": "#F44336"}
  ]
}

Daily Attendance Status

Get class attendance status for a specific date.

Endpoint: GET /api/attendances/daily-status

Query Parameters:

class_id - Class UUID
date - Date (YYYY-MM-DD)

Response:

{
  "success": true,
  "data": {
    "date": "2024-01-15",
    "class": { "id": "...", "name": "Class 10A" },
    "students": [
      {
        "student_id": "...",
        "student_name": "John Doe",
        "student_code": "STD001",
        "status": "Present",
        "attendance_id": "..."
      }
    ],
    "summary": {
      "total": 30,
      "present": 25,
      "late": 2,
      "absent": 3
    }
  }
}

Daily Course Attendance Status

Endpoint: GET /api/attendances/daily-status-course

Query Parameters:

course_id - Course UUID
date - Date (YYYY-MM-DD)

Attendance Report

Get attendance report for date range.

Endpoint: GET /api/attendances/report

Query Parameters:

class_id or course_id
start_date
end_date
group_by - day, week, month

Attendance Reports

Courses Without Attendance

Find courses that haven’t taken attendance.

Endpoint: GET /api/attendance-reports/missing-attendance

Query Parameters:

date - Date to check
academic_session_id - Academic session

Response:

{
  "success": true,
  "data": {
    "courses": [
      {
        "id": "course-uuid",
        "name": "Mathematics 10A",
        "code": "MATH10A",
        "scheduled_periods": 2,
        "attendance_taken": 0
      }
    ],
    "total_missing": 5
  }
}

Export Missing Attendance Report

Endpoint: GET /api/attendance-reports/missing-attendance/export

Returns Excel file with missing attendance details.

Filtering

By Date Range

{
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "attendance_date", "operator": ">=", "value": "2024-01-01"},
      {"field": "attendance_date", "operator": "<=", "value": "2024-01-31"}
    ]
  }
}

By Status

{
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "status", "operator": "in", "value": ["AbsentRequest", "AbsentNoRequest"]}
    ]
  }
}

By Class and Date

{
  "filter": {
    "group": "AND",
    "conditions": [
      {"field": "class_id", "operator": "=", "value": "class-uuid"},
      {"field": "attendance_date", "operator": "=", "value": "2024-01-15"}
    ]
  }
}

Duplicate Handling

The API automatically handles duplicates:

Within Request: Last occurrence wins for duplicate student IDs
Existing Records: Updates existing attendance for same student/date/class combination

Response indicates duplicates handled:

{
  "data": {
    "created": 25,
    "duplicates_handled": 5,
    "original_count": 30
  }
}

Code Examples

Take Class Attendance

const takeAttendance = async (classId, date, students) => {
  const response = await fetch('/api/attendances/class-attendance', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-Team-ID': teamId,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      date: date,
      class_id: classId,
      attendances: students.map(s => ({
        student_id: s.id,
        status: s.status,
        comment: s.comment
      }))
    })
  });

  return response.json();
};

Get Monthly Attendance Summary

const getMonthlyAttendance = async (studentId, year, month) => {
  const startDate = `${year}-${month.toString().padStart(2, '0')}-01`;
  const endDate = `${year}-${month.toString().padStart(2, '0')}-31`;

  const response = await fetch(
    `/api/attendances/student/${studentId}?start_date=${startDate}&end_date=${endDate}`,
    {
      headers: {
        'Authorization': `Bearer ${token}`,
        'X-Team-ID': teamId
      }
    }
  );

  return response.json();
};

Integration Notes

Attendance records are automatically linked to the current academic session
When taking course attendance, the timetable period can be linked for scheduling reference
Attendance data syncs to Canvas LMS if integration is enabled
Leave applications can auto-update attendance status when approved