{"openapi":"3.1.0","info":{"title":"School360 API","version":"1.0.0","description":"The School360 REST API for a school's own systems: biometric attendance, bank and wallet payments, SMS gateways, accounting and more. Create a key in School Setup › Integrations (Enterprise package) and send it as `Authorization: Bearer <key>`. JSON only, camelCase, ISO dates, amounts in PKR as numbers. Lists are cursor-paged. 120 requests a minute per key.","contact":{"name":"School360","url":"https://developers.school360.cloud/"}},"servers":[{"url":"https://api.school360.cloud/v1"}],"security":[{"apiKey":[]}],"tags":[{"name":"School","description":"The school's structure: campuses, sessions, classes, sections and subjects. Every key can read it."},{"name":"Students","description":"Students: lists, profiles, their attendance, fees and results, and profile updates."},{"name":"Families","description":"Families: parents' and guardians' contacts, children and balance."},{"name":"Admissions","description":"Admission applications from the school's website or forms, and enrolling them."},{"name":"Attendance","description":"Registers, attendance summaries, staff attendance and biometric punches."},{"name":"Fees","description":"Fee vouchers, defaulters, receipts and payments from banks and wallets."},{"name":"Exams","description":"Exams, published results and entering marks."},{"name":"Staff","description":"Staff and their work details (pay only with salaries:read)."},{"name":"Gate","description":"The gate's pick-up and drop-off log."},{"name":"Notices","description":"The notice board: reading and posting notices."},{"name":"Changes","description":"A polling feed of what changed, for tools without webhooks."}],"paths":{"/school":{"get":{"operationId":"getSchool","tags":["School"],"summary":"The school","description":"The school this key belongs to. Any key can read this.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"legalName":{"type":["string","null"]},"type":{"type":"string"},"city":{"type":["string","null"]},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"currency":{"type":"string"},"timezone":{"type":"string"},"website":{"type":"string"}},"required":["code","name","legalName","type","city","country","address","phone","email","currency","timezone","website"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/campuses":{"get":{"operationId":"getCampuses","tags":["School"],"summary":"Campuses","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"name":{"type":"string"},"city":{"type":["string","null"]},"address":{"type":["string","null"]},"phone":{"type":["string","null"]},"isMain":{"type":"boolean"},"isActive":{"type":"boolean"}},"required":["id","code","name","city","address","phone","isMain","isActive"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"description":"Any key can read this."}},"/years":{"get":{"operationId":"getYears","tags":["School"],"summary":"Academic sessions","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"status":{"type":"string","description":"current | upcoming | closed"},"startDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"endDate":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["id","name","status","startDate","endDate"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"description":"Any key can read this."}},"/classes":{"get":{"operationId":"getClasses","tags":["School"],"summary":"Classes","parameters":[{"name":"campusId","in":"query","required":false,"description":"Only this campus's classes.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"level":{"type":["string","null"]},"campusId":{"type":["number","null"]},"sortOrder":{"type":"number"}},"required":["id","name","level","campusId","sortOrder"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"description":"Any key can read this."}},"/sections":{"get":{"operationId":"getSections","tags":["School"],"summary":"Class sections","parameters":[{"name":"classId","in":"query","required":false,"description":"Only this class's sections.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"classId":{"type":"number"},"name":{"type":"string"},"capacity":{"type":["number","null"]}},"required":["id","classId","name","capacity"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"description":"Any key can read this."}},"/subjects":{"get":{"operationId":"getSubjects","tags":["School"],"summary":"Subjects","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":["string","null"]},"name":{"type":"string"},"type":{"type":["string","null"]}},"required":["id","code","name","type"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}},"description":"Any key can read this."}},"/students":{"get":{"operationId":"getStudents","tags":["Students"],"summary":"List students","description":"Students in id order. Every status by default; filter with status. updatedSince returns students added or changed since then.\n\nNeeds the **students:read** permission.","x-permission":"students:read","parameters":[{"name":"q","in":"query","required":false,"description":"Search: name or admission number (with families:read also the parents' names, and 4+ digits match B-Form, CNIC and phone numbers).","schema":{"type":"string","maxLength":80}},{"name":"classId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"sectionId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"status","in":"query","required":false,"description":"active, suspended, left… ","schema":{"type":"string","pattern":"^[a-z][a-z-]{1,29}$"}},{"name":"updatedSince","in":"query","required":false,"description":"ISO date-time, e.g. 2026-10-01T00:00:00Z.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"admissionNo":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gender":{"type":["string","null"]},"dob":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"familyId":{"type":["number","null"]},"rollNo":{"type":["number","null"]},"status":{"type":"string","description":"active, suspended, left, graduated… (the school's student statuses)."},"admissionDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"cardNo":{"description":"Attendance card / biometric id.","type":["string","null"]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"bForm":{"description":"B-Form number. Only for keys with families:read.","type":"string"},"family":{"description":"The family's names and phone. Only for keys with families:read.","anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"fatherName":{"type":"string"},"motherName":{"type":"string"},"phone":{"type":"string","description":"The primary contact's phone."}},"required":["id","code","fatherName","motherName","phone"],"additionalProperties":false},{"type":"null"}]}},"required":["id","admissionNo","firstName","lastName","gender","dob","classId","sectionId","campusId","familyId","rollNo","status","admissionDate","cardNo","updatedAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/students/{id}":{"get":{"operationId":"getStudentsById","tags":["Students"],"summary":"One student","x-permission":"students:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"admissionNo":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gender":{"type":["string","null"]},"dob":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"familyId":{"type":["number","null"]},"rollNo":{"type":["number","null"]},"status":{"type":"string","description":"active, suspended, left, graduated… (the school's student statuses)."},"admissionDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"cardNo":{"description":"Attendance card / biometric id.","type":["string","null"]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"bForm":{"description":"B-Form number. Only for keys with families:read.","type":"string"},"family":{"description":"The family's names and phone. Only for keys with families:read.","anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"fatherName":{"type":"string"},"motherName":{"type":"string"},"phone":{"type":"string","description":"The primary contact's phone."}},"required":["id","code","fatherName","motherName","phone"],"additionalProperties":false},{"type":"null"}]}},"required":["id","admissionNo","firstName","lastName","gender","dob","classId","sectionId","campusId","familyId","rollNo","status","admissionDate","cardNo","updatedAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}},"description":"Needs the **students:read** permission."},"patch":{"operationId":"patchStudentsById","tags":["Students"],"summary":"Update a student's details","description":"Changes a student's attendance card number and a few profile details. Only the fields sent change; send null (or \"\") to clear one. The B-Form number needs families:write too. Class, section, status, names and dates are changed in the portal only. The student.updated webhook fires.\n\nNeeds the **students:write** permission.","x-permission":"students:write","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cardNo":{"description":"Attendance card / biometric id: unique among current students.","anyOf":[{"type":"string","maxLength":30},{"type":"null"}]},"bloodGroup":{"description":"A blood-group value of the school's list, e.g. a-pos, o-neg.","anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"religion":{"description":"A religion value of the school's list.","anyOf":[{"type":"string","maxLength":30},{"type":"null"}]},"medical":{"description":"Medical notes.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"previousSchool":{"anyOf":[{"type":"string","maxLength":150},{"type":"null"}]},"bForm":{"description":"B-Form / CRC number. Needs families:write.","anyOf":[{"type":"string","pattern":"^\\d{5}-\\d{7}-\\d$"},{"type":"string","const":""},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"admissionNo":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"gender":{"type":["string","null"]},"dob":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"familyId":{"type":["number","null"]},"rollNo":{"type":["number","null"]},"status":{"type":"string","description":"active, suspended, left, graduated… (the school's student statuses)."},"admissionDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"cardNo":{"description":"Attendance card / biometric id.","type":["string","null"]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"bForm":{"description":"B-Form number. Only for keys with families:read.","type":"string"},"family":{"description":"The family's names and phone. Only for keys with families:read.","anyOf":[{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"fatherName":{"type":"string"},"motherName":{"type":"string"},"phone":{"type":"string","description":"The primary contact's phone."}},"required":["id","code","fatherName","motherName","phone"],"additionalProperties":false},{"type":"null"}]}},"required":["id","admissionNo","firstName","lastName","gender","dob","classId","sectionId","campusId","familyId","rollNo","status","admissionDate","cardNo","updatedAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/families":{"get":{"operationId":"getFamilies","tags":["Families"],"summary":"List families","description":"Families with their parents' and guardian's details, in id order.\n\nNeeds the **families:read** permission.","x-permission":"families:read","parameters":[{"name":"q","in":"query","required":false,"description":"Search: family code, a parent's name, or 4+ digits of a CNIC or phone number.","schema":{"type":"string","maxLength":80}},{"name":"updatedSince","in":"query","required":false,"description":"ISO date-time.","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"surname":{"type":"string"},"father":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"},"cnic":{"type":"string"}},"required":["name","phone","email","occupation","cnic"],"additionalProperties":false},"mother":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"}},"required":["name","phone","email","occupation"],"additionalProperties":false},"guardian":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"relation":{"type":"string"},"phone":{"type":"string"},"cnic":{"type":"string"},"email":{"type":"string"}},"required":["name","relation","phone","cnic","email"],"additionalProperties":false},{"type":"null"}]},"primaryContact":{"type":["string","null"]},"address":{"type":"string"},"city":{"type":"string"},"due":{"description":"Unpaid on the family's vouchers (lists only). Only for keys with fees:read.","type":"number"}},"required":["id","code","surname","father","mother","guardian","primaryContact","address","city"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/families/{id}":{"get":{"operationId":"getFamiliesById","tags":["Families"],"summary":"One family","description":"A family with its children (on the key's campus) and, for keys with fees:read, its balance.\n\nNeeds the **families:read** permission.","x-permission":"families:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"surname":{"type":"string"},"father":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"},"cnic":{"type":"string"}},"required":["name","phone","email","occupation","cnic"],"additionalProperties":false},"mother":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"}},"required":["name","phone","email","occupation"],"additionalProperties":false},"guardian":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"relation":{"type":"string"},"phone":{"type":"string"},"cnic":{"type":"string"},"email":{"type":"string"}},"required":["name","relation","phone","cnic","email"],"additionalProperties":false},{"type":"null"}]},"primaryContact":{"type":["string","null"]},"address":{"type":"string"},"city":{"type":"string"},"due":{"description":"Unpaid on the family's vouchers (lists only). Only for keys with fees:read.","type":"number"},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"admissionNo":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"status":{"type":"string"}},"required":["id","admissionNo","firstName","lastName","classId","sectionId","campusId","status"],"additionalProperties":false}},"balance":{"description":"Only for keys with fees:read.","type":"object","properties":{"due":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"credit":{"type":"number","description":"Advance paid, kept for the next vouchers."}},"required":["due","credit"],"additionalProperties":false}},"required":["id","code","surname","father","mother","guardian","primaryContact","address","city","children"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"patch":{"operationId":"patchFamiliesById","tags":["Families"],"summary":"Update a family's contact details","description":"Changes the parents' and guardian's phone numbers and emails, the primary contact and the address. Only the fields sent change; \"\" clears one. The family must keep a parent's or the guardian's phone. Names and CNICs are changed in the portal only, and parents app accounts aren't changed (the school updates those on the family form).\n\nNeeds the **families:write** permission.","x-permission":"families:write","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"father":{"type":"object","properties":{"phone":{"type":"string","maxLength":30},"email":{"anyOf":[{"type":"string","maxLength":150,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","const":""}]}}},"mother":{"type":"object","properties":{"phone":{"type":"string","maxLength":30},"email":{"anyOf":[{"type":"string","maxLength":150,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","const":""}]}}},"guardian":{"description":"Only for a family with a guardian.","type":"object","properties":{"phone":{"type":"string","maxLength":30},"email":{"anyOf":[{"type":"string","maxLength":150,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","const":""}]}}},"primaryContact":{"type":"string","enum":["father","mother","guardian"]},"address":{"type":"string","maxLength":300},"city":{"type":"string","maxLength":60}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string"},"surname":{"type":"string"},"father":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"},"cnic":{"type":"string"}},"required":["name","phone","email","occupation","cnic"],"additionalProperties":false},"mother":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"}},"required":["name","phone","email","occupation"],"additionalProperties":false},"guardian":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"relation":{"type":"string"},"phone":{"type":"string"},"cnic":{"type":"string"},"email":{"type":"string"}},"required":["name","relation","phone","cnic","email"],"additionalProperties":false},{"type":"null"}]},"primaryContact":{"type":["string","null"]},"address":{"type":"string"},"city":{"type":"string"},"due":{"description":"Unpaid on the family's vouchers (lists only). Only for keys with fees:read.","type":"number"}},"required":["id","code","surname","father","mother","guardian","primaryContact","address","city"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/applications":{"get":{"operationId":"getApplications","tags":["Admissions"],"summary":"List applications","description":"Admission applications in id order, every session unless yearId is given.\n\nNeeds the **admissions:read** permission.","x-permission":"admissions:read","parameters":[{"name":"status","in":"query","required":false,"description":"inquiry | applied | test-scheduled | approved | enrolled | rejected","schema":{"type":"string","enum":["inquiry","applied","test-scheduled","approved","enrolled","rejected"]}},{"name":"yearId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"classId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string","description":"The application (admission enquiry) number, e.g. ADM-2026-0088."},"status":{"type":"string","enum":["inquiry","applied","test-scheduled","approved","enrolled","rejected"],"description":"inquiry | applied | test-scheduled | approved | enrolled | rejected"},"yearId":{"type":"number"},"classId":{"type":"number"},"campusId":{"type":["number","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"},"gender":{"type":"string"},"dob":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"father":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"},"cnic":{"description":"Only for keys with families:read.","type":"string"}},"required":["name","phone","email","occupation"],"additionalProperties":false},"mother":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"}},"required":["name","phone"],"additionalProperties":false},"address":{"description":"Only for keys with families:read.","type":"string"},"source":{"type":["string","null"]},"previousSchool":{"type":["string","null"]},"appliedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"test":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"time":{"type":["string","null"]},"marks":{"type":["number","null"]},"outOf":{"type":["number","null"]}},"required":["kind","date","time","marks","outOf"],"additionalProperties":false},{"type":"null"}]},"decision":{"anyOf":[{"type":"object","properties":{"on":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"reason":{"type":["string","null"]}},"required":["on","reason"],"additionalProperties":false},{"type":"null"}]},"familyId":{"description":"A family already at the school (a brother or sister), or the family once enrolled.","type":["number","null"]},"studentId":{"description":"The student, once enrolled.","type":["number","null"]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","status","yearId","classId","campusId","firstName","lastName","gender","dob","father","mother","source","previousSchool","appliedOn","test","decision","familyId","studentId","updatedAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postApplications","tags":["Admissions"],"summary":"Take an application","description":"An admission enquiry from the school's own website, form or app. It gets the next application number and starts at inquiry on Students › Admissions, exactly like one taken at the front desk (a family already at the school with the same father's CNIC or phone is noted as a brother or sister). The parents need a name (father or mother) and a phone. The application.received webhook fires.\n\nNeeds the **admissions:write** permission.","x-permission":"admissions:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"classId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"The class applied for (GET /classes)."},"yearId":{"description":"The session (GET /years). Default: the current one, else the next.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"firstName":{"type":"string","minLength":1,"maxLength":60},"lastName":{"type":"string","maxLength":60},"gender":{"type":"string","enum":["male","female"]},"dob":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"father":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"phone":{"type":"string","maxLength":30},"cnic":{"anyOf":[{"type":"string","pattern":"^\\d{5}-\\d{7}-\\d$"},{"type":"string","const":""}]},"occupation":{"type":"string","maxLength":80},"email":{"anyOf":[{"type":"string","maxLength":150,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"string","const":""}]}}},"mother":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"phone":{"type":"string","maxLength":30}}},"address":{"type":"string","maxLength":300},"source":{"description":"How they heard of the school (an admission-source value). Default: website.","type":"string","pattern":"^[a-z0-9-]{2,40}$"},"previousSchool":{"type":"string","maxLength":150},"notes":{"type":"string","maxLength":1500}},"required":["classId","firstName","gender"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string","description":"The application (admission enquiry) number, e.g. ADM-2026-0088."},"status":{"type":"string","enum":["inquiry","applied","test-scheduled","approved","enrolled","rejected"],"description":"inquiry | applied | test-scheduled | approved | enrolled | rejected"},"yearId":{"type":"number"},"classId":{"type":"number"},"campusId":{"type":["number","null"]},"firstName":{"type":"string"},"lastName":{"type":"string"},"gender":{"type":"string"},"dob":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"father":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"occupation":{"type":"string"},"cnic":{"description":"Only for keys with families:read.","type":"string"}},"required":["name","phone","email","occupation"],"additionalProperties":false},"mother":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"}},"required":["name","phone"],"additionalProperties":false},"address":{"description":"Only for keys with families:read.","type":"string"},"source":{"type":["string","null"]},"previousSchool":{"type":["string","null"]},"appliedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"test":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string"},"date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"time":{"type":["string","null"]},"marks":{"type":["number","null"]},"outOf":{"type":["number","null"]}},"required":["kind","date","time","marks","outOf"],"additionalProperties":false},{"type":"null"}]},"decision":{"anyOf":[{"type":"object","properties":{"on":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"reason":{"type":["string","null"]}},"required":["on","reason"],"additionalProperties":false},{"type":"null"}]},"familyId":{"description":"A family already at the school (a brother or sister), or the family once enrolled.","type":["number","null"]},"studentId":{"description":"The student, once enrolled.","type":["number","null"]},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","status","yearId","classId","campusId","firstName","lastName","gender","dob","father","mother","source","previousSchool","appliedOn","test","decision","familyId","studentId","updatedAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/applications/{id}/enrol":{"post":{"operationId":"postApplicationsByIdEnrol","tags":["Admissions"],"summary":"Enrol an application","description":"Admits the child of an open application for this session as a student, as the student form does: the next admission number, the end of the section's roll, this session's enrolment, and a family (the brother or sister's family already here, else a new one from the application). The application is marked enrolled. Applications for the next session join at the year-end promotion instead (422). The student.admitted and application.status_changed webhooks fire.\n\nNeeds the **admissions:write** permission.","x-permission":"admissions:write","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sectionId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"A section of the class applied for (GET /sections?classId=)."},"admissionDate":{"description":"Default: today.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"dob":{"description":"Required when the application has none.","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"lastName":{"type":"string","minLength":1,"maxLength":60},"bForm":{"anyOf":[{"type":"string","pattern":"^\\d{5}-\\d{7}-\\d$"},{"type":"string","const":""}]},"cardNo":{"description":"Attendance card / biometric id.","type":"string","maxLength":30}},"required":["sectionId"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"number"},"admissionNo":{"type":"string"},"familyId":{"type":"number"},"applicationId":{"type":"number"},"applicationNumber":{"type":"string"}},"required":["studentId","admissionNo","familyId","applicationId","applicationNumber"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/attendance":{"get":{"operationId":"getAttendance","tags":["Attendance"],"summary":"A section's register for a day","description":"What was marked: the register's exceptions (absent, late, leave, half-day, and present with a remark). Every other student on the roll that day was present. taken is false when no register was marked.\n\nNeeds the **attendance:read** permission.","x-permission":"attendance:read","parameters":[{"name":"sectionId","in":"query","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sectionId":{"type":"number"},"classId":{"type":"number"},"campusId":{"type":["number","null"]},"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"taken":{"type":"boolean"},"registerId":{"type":["number","null"]},"markedBy":{"type":["string","null"]},"markedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"onRoll":{"type":"number","description":"Students on the section's roll that day."},"marks":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"number"},"status":{"type":"string","enum":["present","absent","late","leave","half-day"],"description":"present | absent | late | leave | half-day"},"remark":{"type":["string","null"]}},"required":["studentId","status","remark"],"additionalProperties":false}}},"required":["sectionId","classId","campusId","date","taken","registerId","markedBy","markedAt","onRoll","marks"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/attendance/summary":{"get":{"operationId":"getAttendanceSummary","tags":["Attendance"],"summary":"Attendance counts over a range","description":"Days present, absent, late, on leave and half-day for one student (studentId) or each student on a section's roll (sectionId), from the registers taken between from and to (at most a year). Days before a student joined don't count.\n\nNeeds the **attendance:read** permission.","x-permission":"attendance:read","parameters":[{"name":"sectionId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"studentId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD). Default: 29 days before to.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"to","in":"query","required":false,"description":"Last day. Default: today.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"to":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"sectionId":{"type":["number","null"]},"studentId":{"type":["number","null"]},"registers":{"type":"number"},"totals":{"type":"object","properties":{"days":{"type":"number","description":"Registers taken (school days) since the student joined."},"present":{"type":"number"},"absent":{"type":"number"},"late":{"type":"number"},"leave":{"type":"number"},"halfDay":{"type":"number"},"rate":{"description":"(present + late + half-day) / days, 0–1; null without registers.","type":["number","null"]}},"required":["days","present","absent","late","leave","halfDay","rate"],"additionalProperties":false},"students":{"type":"array","items":{"type":"object","properties":{"days":{"type":"number","description":"Registers taken (school days) since the student joined."},"present":{"type":"number"},"absent":{"type":"number"},"late":{"type":"number"},"leave":{"type":"number"},"halfDay":{"type":"number"},"rate":{"description":"(present + late + half-day) / days, 0–1; null without registers.","type":["number","null"]},"studentId":{"type":"number"}},"required":["days","present","absent","late","leave","halfDay","rate","studentId"],"additionalProperties":false}}},"required":["from","to","sectionId","studentId","registers","totals","students"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/students/{id}/attendance":{"get":{"operationId":"getStudentsByIdAttendance","tags":["Attendance"],"summary":"A student's attendance, day by day","description":"Each register taken in the student's section between from and to (default the last 30 days, at most a year) with their status that day.\n\nNeeds the **attendance:read** permission.","x-permission":"attendance:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD). Default: 29 days before to.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"to","in":"query","required":false,"description":"Last day. Default: today.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"number"},"sectionId":{"type":["number","null"]},"from":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"to":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"days":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"status":{"type":"string","enum":["present","absent","late","leave","half-day"]},"remark":{"type":["string","null"]}},"required":["date","status","remark"],"additionalProperties":false}},"totals":{"type":"object","properties":{"days":{"type":"number","description":"Registers taken (school days) since the student joined."},"present":{"type":"number"},"absent":{"type":"number"},"late":{"type":"number"},"leave":{"type":"number"},"halfDay":{"type":"number"},"rate":{"description":"(present + late + half-day) / days, 0–1; null without registers.","type":["number","null"]}},"required":["days","present","absent","late","leave","halfDay","rate"],"additionalProperties":false}},"required":["studentId","sectionId","from","to","days","totals"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/staff/attendance":{"get":{"operationId":"getStaffAttendance","tags":["Attendance"],"summary":"Staff attendance for a day","description":"The staff sheet for a day: each member of staff marked (or punched) that day with their status, check-in and check-out. Staff not listed weren't marked.\n\nNeeds the **attendance:read** permission.","x-permission":"attendance:read","parameters":[{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"data":{"type":"array","items":{"type":"object","properties":{"staffId":{"type":"number"},"code":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"campusId":{"type":["number","null"]},"status":{"type":"string","enum":["present","absent","late","leave","half-day"]},"checkIn":{"type":["string","null"]},"checkOut":{"type":["string","null"]},"note":{"type":["string","null"]}},"required":["staffId","code","firstName","lastName","campusId","status","checkIn","checkOut","note"],"additionalProperties":false}}},"required":["date","data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postStaffAttendance","tags":["Attendance"],"summary":"Send a day of staff attendance","description":"Each entry replaces that staff member's day (status, check-in, check-out). Staff not listed are left as they are.\n\nNeeds the **attendance:write** permission.","x-permission":"attendance:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"entries":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"staffCode":{"type":"string","minLength":1,"maxLength":40},"status":{"type":"string","enum":["present","absent","late","leave","half-day"],"description":"present | absent | late | leave | half-day"},"in":{"description":"Check-in, HH:MM (24 h).","type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"out":{"description":"Check-out, HH:MM (24 h).","type":"string","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"note":{"type":"string","maxLength":200}},"required":["staffCode","status"]}}},"required":["date","entries"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number"},"staffCode":{"type":"string"},"staffId":{"type":["number","null"]},"status":{"type":"string","enum":["applied","unknown_person"]}},"required":["index","staffCode","staffId","status"],"additionalProperties":false}},"applied":{"type":"number"},"unknown":{"type":"number"}},"required":["results","applied","unknown"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/attendance/registers":{"post":{"operationId":"postAttendanceRegisters","tags":["Attendance"],"summary":"Mark a section's register","description":"A section's register for a school day, as the portal saves it: send the exceptions (absent, late, leave, half-day, or present with a remark); every other student on the roll is present. Saving again replaces the day's marks. Students not on the section's roll are ignored (listed in ignored). Parents get the school's absence messages and the student.absent, student.late and attendance.register_saved webhooks fire as for a register marked in the portal.\n\nNeeds the **attendance:write** permission.","x-permission":"attendance:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sectionId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"marks":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"studentId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["present","absent","late","leave","half-day"],"description":"present | absent | late | leave | half-day"},"remark":{"type":"string","maxLength":200}},"required":["studentId","status"]}}},"required":["sectionId","date","marks"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"registerId":{"type":"number"},"sectionId":{"type":"number"},"date":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"marked":{"type":"number","description":"Exceptions stored."},"ignored":{"type":"array","items":{"type":"number"},"description":"studentIds not on the section's roll."}},"required":["registerId","sectionId","date","marked","ignored"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/attendance/punches":{"post":{"operationId":"postAttendancePunches","tags":["Attendance"],"summary":"Send biometric punches","description":"Up to 500 punches from attendance machines. Students: the first \"in\" of the day marks them present, or late after the school's late time, in their section's register (a register is started if there isn't one; absent is never set by a punch, and a mark someone already made is kept, except absent which becomes present or late). Staff: their day's status (present / late) with the earliest check-in and latest check-out. Each punch (person, time, direction) counts once. Punches older than 7 days, in the future, or on a day the school is closed are outside_window.\n\nNeeds the **attendance:write** permission.","x-permission":"attendance:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"punches":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"When, as ISO date-time with its offset (e.g. 2026-10-08T07:52:10+05:00)."},"personType":{"type":"string","enum":["student","staff"]},"identifier":{"type":"object","properties":{"admissionNo":{"type":"string","minLength":1,"maxLength":40},"rollNo":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"sectionId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"staffCode":{"type":"string","minLength":1,"maxLength":40},"cardNo":{"type":"string","minLength":1,"maxLength":30}},"description":"Who punched. Students: admissionNo, rollNo + sectionId, or cardNo. Staff: staffCode or cardNo."},"direction":{"type":"string","enum":["in","out"]},"deviceId":{"description":"The machine's id or name, kept with the punch.","type":"string","maxLength":60}},"required":["at","personType","identifier","direction"]}}},"required":["punches"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"number","description":"The punch's position in the request (from 0)."},"status":{"type":"string","enum":["applied","duplicate","unknown_person","outside_window"]},"personType":{"type":"string","enum":["student","staff"]},"personId":{"type":["number","null"]},"message":{"type":["string","null"]}},"required":["index","status","personType","personId","message"],"additionalProperties":false}},"applied":{"type":"number"},"duplicates":{"type":"number"},"unknown":{"type":"number"},"outsideWindow":{"type":"number"}},"required":["results","applied","duplicates","unknown","outsideWindow"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/vouchers":{"get":{"operationId":"getVouchers","tags":["Fees"],"summary":"List fee vouchers","description":"Vouchers (fee challans) in id order. status: open (anything unpaid), paid, overdue (unpaid after the due date).\n\nNeeds the **fees:read** permission.","x-permission":"fees:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["open","paid","overdue"]}},{"name":"month","in":"query","required":false,"description":"YYYY-MM","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}},{"name":"familyId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"studentId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"studentId":{"type":"number"},"familyId":{"type":["number","null"]},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"month":{"type":"string","description":"YYYY-MM"},"issuedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"dueOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"total":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"paid":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"balance":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"fineAmount":{"type":"number","description":"The late fine charged once the voucher is overdue."},"lateFine":{"type":"number","description":"Late fine already paid."},"status":{"type":"string","enum":["unpaid","partial","paid","overdue","cancelled"]},"lines":{"description":"Fee heads (GET /vouchers/{id} only).","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","number","studentId","familyId","classId","sectionId","campusId","month","issuedOn","dueOn","total","paid","balance","fineAmount","lateFine","status"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/vouchers/{id}":{"get":{"operationId":"getVouchersById","tags":["Fees"],"summary":"One fee voucher","x-permission":"fees:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"studentId":{"type":"number"},"familyId":{"type":["number","null"]},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"month":{"type":"string","description":"YYYY-MM"},"issuedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"dueOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"total":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"paid":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"balance":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"fineAmount":{"type":"number","description":"The late fine charged once the voucher is overdue."},"lateFine":{"type":"number","description":"Late fine already paid."},"status":{"type":"string","enum":["unpaid","partial","paid","overdue","cancelled"]},"lines":{"description":"Fee heads (GET /vouchers/{id} only).","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","number","studentId","familyId","classId","sectionId","campusId","month","issuedOn","dueOn","total","paid","balance","fineAmount","lateFine","status"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}},"description":"Needs the **fees:read** permission."}},"/defaulters":{"get":{"operationId":"getDefaulters","tags":["Fees"],"summary":"Fee defaulters","description":"Students with fees unpaid after the due date, the longest behind first (the order of Finance › Defaulters).\n\nNeeds the **fees:read** permission.","x-permission":"fees:read","parameters":[{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"student":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"admissionNo":{"type":"string"},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"status":{"type":"string"}},"required":["id","name","admissionNo","classId","sectionId","status"],"additionalProperties":false},"family":{"type":"object","properties":{"id":{"type":["number","null"]},"code":{"type":"string"},"name":{"type":"string"},"phone":{"description":"Only for keys with families:read.","type":"string"}},"required":["id","code","name"],"additionalProperties":false},"months":{"type":"array","items":{"type":"string"},"description":"Months unpaid (YYYY-MM), oldest first."},"amount":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"fines":{"type":"number","description":"Late fines due on top."},"lastPaid":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]}},"required":["student","family","months","amount","fines","lastPaid"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/receipts":{"get":{"operationId":"getReceipts","tags":["Fees"],"summary":"List fee receipts","description":"Receipts (money received) in id order, newest last. Filter by family and by the day received (from, to). Cancelled receipts are included with cancelled: true.\n\nNeeds the **fees:read** permission.","x-permission":"fees:read","parameters":[{"name":"familyId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"from","in":"query","required":false,"description":"Received on or after (YYYY-MM-DD).","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"to","in":"query","required":false,"description":"Received on or before.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"method","in":"query","required":false,"description":"A payment method, e.g. cash, ibft.","schema":{"type":"string","pattern":"^[a-z0-9-]{2,30}$"}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"amount":{"type":"number","description":"Received, late fines included."},"lateFine":{"type":"number","description":"Of which late fines."},"familyId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"method":{"type":"string"},"reference":{"type":["string","null"]},"receivedOn":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"cancelled":{"type":"boolean"},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","number","amount","lateFine","familyId","campusId","method","reference","receivedOn","cancelled","createdAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/receipts/{id}":{"get":{"operationId":"getReceiptsById","tags":["Fees"],"summary":"One fee receipt","description":"A receipt with what it paid: each voucher, its student and month, and the late fine paid on it.\n\nNeeds the **fees:read** permission.","x-permission":"fees:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"amount":{"type":"number","description":"Received, late fines included."},"lateFine":{"type":"number","description":"Of which late fines."},"familyId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"method":{"type":"string"},"reference":{"type":["string","null"]},"receivedOn":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"cancelled":{"type":"boolean"},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"voucherId":{"type":"number"},"voucherNumber":{"type":"string"},"studentId":{"type":"number"},"month":{"type":"string"},"amount":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"fine":{"type":"number","description":"An amount in the school's currency (PKR), as a number."}},"required":["voucherId","voucherNumber","studentId","month","amount","fine"],"additionalProperties":false}}},"required":["id","number","amount","lateFine","familyId","campusId","method","reference","receivedOn","cancelled","createdAt","lines"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/students/{id}/fees":{"get":{"operationId":"getStudentsByIdFees","tags":["Fees"],"summary":"A student's fees","description":"What the student owes (unpaid and overdue, over all their vouchers) and their vouchers, newest month first (limit, default 12).\n\nNeeds the **fees:read** permission.","x-permission":"fees:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"limit","in":"query","required":false,"description":"How many vouchers (1–120, default 12).","schema":{"default":12,"type":"integer","minimum":1,"maximum":120}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"number"},"familyId":{"type":["number","null"]},"due":{"type":"number","description":"Unpaid on every voucher not cancelled."},"overdue":{"type":"number","description":"Unpaid after the due date."},"vouchers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string"},"studentId":{"type":"number"},"familyId":{"type":["number","null"]},"classId":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"month":{"type":"string","description":"YYYY-MM"},"issuedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"dueOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"total":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"paid":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"balance":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"fineAmount":{"type":"number","description":"The late fine charged once the voucher is overdue."},"lateFine":{"type":"number","description":"Late fine already paid."},"status":{"type":"string","enum":["unpaid","partial","paid","overdue","cancelled"]},"lines":{"description":"Fee heads (GET /vouchers/{id} only).","type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","number","studentId","familyId","classId","sectionId","campusId","month","issuedOn","dueOn","total","paid","balance","fineAmount","lateFine","status"],"additionalProperties":false}}},"required":["studentId","familyId","due","overdue","vouchers"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/payments":{"post":{"operationId":"postPayments","tags":["Fees"],"summary":"Record a payment","description":"A payment confirmed by a bank, 1Link, JazzCash, Easypaisa… becomes a receipt from the school's normal receipt series, exactly as if taken at the fee counter: late fines first, then the oldest vouchers. Name the family (familyId or familyCode) to pay its open vouchers, or voucherNumber to pay one voucher. An Idempotency-Key header is required, and the same method + reference can't be recorded twice. The receipt is dated today; paidAt and note are kept on it.\n\nNeeds the **fees:write** permission.","x-permission":"fees:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"familyId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"familyCode":{"type":"string","minLength":1,"maxLength":30},"voucherNumber":{"type":"string","minLength":1,"maxLength":40},"amount":{"type":"number","exclusiveMinimum":0,"maximum":100000000,"description":"PKR received."},"method":{"type":"string","pattern":"^[a-z0-9-]{2,30}$","description":"A payment method of the school (Finance › Fields & Options › Payment methods), e.g. bank-deposit, ibft, jazzcash, easypaisa, cash."},"reference":{"description":"The bank's or wallet's transaction id. Required unless method is cash.","type":"string","maxLength":80},"paidAt":{"description":"When the money was paid (kept on the receipt's note).","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"note":{"type":"string","maxLength":200}},"required":["amount","method"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"number":{"type":"string","description":"The receipt number, from the school's receipt series."},"amount":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"familyId":{"type":"number"},"method":{"type":"string"},"reference":{"type":["string","null"]},"receivedOn":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"lines":{"type":"array","items":{"type":"object","properties":{"voucherId":{"type":"number"},"voucherNumber":{"type":"string"},"amount":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"fine":{"type":"number","description":"Late fine paid on this voucher."}},"required":["voucherId","voucherNumber","amount","fine"],"additionalProperties":false}}},"required":["id","number","amount","familyId","method","reference","receivedOn","lines"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/exams":{"get":{"operationId":"getExams","tags":["Exams"],"summary":"List exams","description":"A session's exams (the current session by default), oldest first, with the classes sitting them.\n\nNeeds the **exams:read** permission.","x-permission":"exams:read","parameters":[{"name":"yearId","in":"query","required":false,"description":"The session (GET /years). Default: the current one.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"status","in":"query","required":false,"description":"draft | scheduled | marking | published","schema":{"type":"string","enum":["draft","scheduled","marking","published"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"type":{"type":"string"},"yearId":{"type":["number","null"]},"termId":{"type":["number","null"]},"startDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"endDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"maxMarks":{"type":["number","null"]},"status":{"type":"string","enum":["draft","scheduled","marking","published"],"description":"draft | scheduled | marking | published"},"publishedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"classIds":{"type":"array","items":{"type":"number"},"description":"Classes sitting it (on the key's campus)."}},"required":["id","name","type","yearId","termId","startDate","endDate","maxMarks","status","publishedOn","classIds"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/results":{"get":{"operationId":"getResults","tags":["Exams"],"summary":"Exam results for a class or section","description":"A published exam's results: each student's marks per paper, total, percentage, grade, pass or fail and position, worked out as the school's report cards are (its grading scheme, pass rule and positions setting). Positions are in the whole class, also when you ask for one section. Students are those on the class's roll. Before the results are published: 404 results_not_published.\n\nNeeds the **exams:read** permission.","x-permission":"exams:read","parameters":[{"name":"examId","in":"query","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"sectionId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"classId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"exam":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"type":{"type":"string"},"yearId":{"type":["number","null"]},"termId":{"type":["number","null"]},"startDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"endDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"maxMarks":{"type":["number","null"]},"status":{"type":"string","enum":["draft","scheduled","marking","published"],"description":"draft | scheduled | marking | published"},"publishedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"classIds":{"type":"array","items":{"type":"number"},"description":"Classes sitting it (on the key's campus)."}},"required":["id","name","type","yearId","termId","startDate","endDate","maxMarks","status","publishedOn","classIds"],"additionalProperties":false},"classId":{"type":"number"},"sectionId":{"type":["number","null"]},"grading":{"type":"object","properties":{"passPercent":{"type":"number"},"rule":{"type":"string","description":"every-subject (pass every paper) | overall (pass on the total)"},"positions":{"type":"boolean","description":"Whether the school shows positions."}},"required":["passPercent","rule","positions"],"additionalProperties":false},"papers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"subjectId":{"type":"number"},"date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"maxMarks":{"type":"number"},"passMarks":{"type":"number"}},"required":["id","subjectId","date","maxMarks","passMarks"],"additionalProperties":false}},"ranked":{"type":"number","description":"Students with a position in the class."},"data":{"type":"array","items":{"type":"object","properties":{"studentId":{"type":"number"},"admissionNo":{"type":"string"},"name":{"type":"string"},"rollNo":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"marks":{"type":"array","items":{"type":"object","properties":{"paperId":{"type":"number"},"subjectId":{"type":"number"},"marks":{"type":["number","null"]},"absent":{"type":"boolean"}},"required":["paperId","subjectId","marks","absent"],"additionalProperties":false}},"total":{"type":"number"},"max":{"type":"number","description":"Out of: the papers sat (papers before the student joined don't count)."},"percentage":{"type":["number","null"]},"grade":{"type":["string","null"]},"remark":{"type":["string","null"]},"passed":{"type":["boolean","null"]},"failedSubjectIds":{"type":"array","items":{"type":"number"}},"position":{"description":"In the whole class (ties share a position); null when the school doesn't show positions or a mark is missing.","type":["number","null"]},"missing":{"type":"number","description":"Papers without a mark."}},"required":["studentId","admissionNo","name","rollNo","sectionId","marks","total","max","percentage","grade","remark","passed","failedSubjectIds","position","missing"],"additionalProperties":false}}},"required":["exam","classId","sectionId","grading","papers","ranked","data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/students/{id}/results":{"get":{"operationId":"getStudentsByIdResults","tags":["Exams"],"summary":"A student's results","description":"The student's results in each published exam of a session (the current one by default), in the class they were enrolled in that session.\n\nNeeds the **exams:read** permission.","x-permission":"exams:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"yearId","in":"query","required":false,"description":"Default: the current session.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"studentId":{"type":"number"},"yearId":{"type":["number","null"]},"classId":{"type":["number","null"]},"data":{"type":"array","items":{"type":"object","properties":{"exam":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"type":{"type":"string"},"yearId":{"type":["number","null"]},"termId":{"type":["number","null"]},"startDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"endDate":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"maxMarks":{"type":["number","null"]},"status":{"type":"string","enum":["draft","scheduled","marking","published"],"description":"draft | scheduled | marking | published"},"publishedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"classIds":{"type":"array","items":{"type":"number"},"description":"Classes sitting it (on the key's campus)."}},"required":["id","name","type","yearId","termId","startDate","endDate","maxMarks","status","publishedOn","classIds"],"additionalProperties":false},"grading":{"type":"object","properties":{"passPercent":{"type":"number"},"rule":{"type":"string","description":"every-subject (pass every paper) | overall (pass on the total)"},"positions":{"type":"boolean","description":"Whether the school shows positions."}},"required":["passPercent","rule","positions"],"additionalProperties":false},"papers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"subjectId":{"type":"number"},"date":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"maxMarks":{"type":"number"},"passMarks":{"type":"number"}},"required":["id","subjectId","date","maxMarks","passMarks"],"additionalProperties":false}},"result":{"type":"object","properties":{"studentId":{"type":"number"},"admissionNo":{"type":"string"},"name":{"type":"string"},"rollNo":{"type":["number","null"]},"sectionId":{"type":["number","null"]},"marks":{"type":"array","items":{"type":"object","properties":{"paperId":{"type":"number"},"subjectId":{"type":"number"},"marks":{"type":["number","null"]},"absent":{"type":"boolean"}},"required":["paperId","subjectId","marks","absent"],"additionalProperties":false}},"total":{"type":"number"},"max":{"type":"number","description":"Out of: the papers sat (papers before the student joined don't count)."},"percentage":{"type":["number","null"]},"grade":{"type":["string","null"]},"remark":{"type":["string","null"]},"passed":{"type":["boolean","null"]},"failedSubjectIds":{"type":"array","items":{"type":"number"}},"position":{"description":"In the whole class (ties share a position); null when the school doesn't show positions or a mark is missing.","type":["number","null"]},"missing":{"type":"number","description":"Papers without a mark."}},"required":["studentId","admissionNo","name","rollNo","sectionId","marks","total","max","percentage","grade","remark","passed","failedSubjectIds","position","missing"],"additionalProperties":false}},"required":["exam","grading","papers","result"],"additionalProperties":false}}},"required":["studentId","yearId","classId","data"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/marks":{"post":{"operationId":"postMarks","tags":["Exams"],"summary":"Enter a paper's marks for a section","description":"Marks for the students of a section on one paper (the date sheet's papers: GET /exams, then the portal's papers), as Examinations › Marks saves them. Each student: marks (0 to the paper's maximum), absent: true, or neither (no mark yet). The sheet is saved as a draft, or locked with submit: true (every student needs a mark or absent). Students not on the sheet are ignored (listed in ignored). A submitted sheet, or an exam whose results are published, is 409 sheet_locked; reopening a sheet is done in the portal.\n\nNeeds the **exams:write** permission.","x-permission":"exams:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paperId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"sectionId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"marks":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"studentId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"marks":{"anyOf":[{"type":"number","minimum":0,"maximum":1000},{"type":"null"}]},"absent":{"type":"boolean"}},"required":["studentId"]}},"submit":{"default":false,"description":"Lock the sheet (submitted).","type":"boolean"}},"required":["paperId","sectionId","marks"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"paperId":{"type":"number"},"sectionId":{"type":"number"},"status":{"type":"string","enum":["draft","submitted"]},"entered":{"type":"number"},"students":{"type":"number","description":"Students on the sheet."},"ignored":{"type":"array","items":{"type":"number"}}},"required":["paperId","sectionId","status","entered","students","ignored"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/staff":{"get":{"operationId":"getStaff","tags":["Staff"],"summary":"List staff","description":"Staff in id order, current staff by default (status=left for former staff, all for both). Pay, bank details and CNICs only with salaries:read.\n\nNeeds the **staff:read** permission.","x-permission":"staff:read","parameters":[{"name":"q","in":"query","required":false,"description":"Search: name or employee number.","schema":{"type":"string","maxLength":80}},{"name":"status","in":"query","required":false,"description":"active (default), left or all.","schema":{"default":"active","type":"string","enum":["active","left","all"]}},{"name":"departmentId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"designationId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"campusId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"updatedSince","in":"query","required":false,"description":"Staff added or changed since (ISO date-time).","schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string","description":"Employee number."},"firstName":{"type":"string"},"lastName":{"type":"string"},"gender":{"type":["string","null"]},"category":{"type":"string","description":"academic | non-academic"},"designation":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"department":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"campusId":{"type":["number","null"]},"employmentType":{"type":["string","null"]},"phone":{"type":"string"},"email":{"type":"string"},"cardNo":{"description":"Attendance card / biometric id.","type":["string","null"]},"joinedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"leftOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"status":{"type":"string","description":"active | left"},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"cnic":{"description":"Only for keys with salaries:read.","type":"string"},"dob":{"description":"Only for keys with salaries:read.","anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"address":{"description":"Only for keys with salaries:read.","type":"string"},"emergencyContact":{"description":"Only for keys with salaries:read.","type":"object","properties":{"name":{"type":"string"},"relation":{"type":"string"},"phone":{"type":"string"}},"required":["name","relation","phone"],"additionalProperties":false},"pay":{"description":"Only for keys with salaries:read.","type":"object","properties":{"basic":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"houseRent":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"conveyance":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"medical":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"gross":{"type":"number","description":"basic + allowances, a month."},"bank":{"type":"string"},"iban":{"type":"string"}},"required":["basic","houseRent","conveyance","medical","gross","bank","iban"],"additionalProperties":false}},"required":["id","code","firstName","lastName","gender","category","designation","department","campusId","employmentType","phone","email","cardNo","joinedOn","leftOn","status","updatedAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/staff/{id}":{"get":{"operationId":"getStaffById","tags":["Staff"],"summary":"One member of staff","x-permission":"staff:read","parameters":[{"name":"id","in":"path","required":true,"description":"The record's id.","schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"code":{"type":"string","description":"Employee number."},"firstName":{"type":"string"},"lastName":{"type":"string"},"gender":{"type":["string","null"]},"category":{"type":"string","description":"academic | non-academic"},"designation":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"department":{"anyOf":[{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},{"type":"null"}]},"campusId":{"type":["number","null"]},"employmentType":{"type":["string","null"]},"phone":{"type":"string"},"email":{"type":"string"},"cardNo":{"description":"Attendance card / biometric id.","type":["string","null"]},"joinedOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"leftOn":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"status":{"type":"string","description":"active | left"},"updatedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"cnic":{"description":"Only for keys with salaries:read.","type":"string"},"dob":{"description":"Only for keys with salaries:read.","anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"address":{"description":"Only for keys with salaries:read.","type":"string"},"emergencyContact":{"description":"Only for keys with salaries:read.","type":"object","properties":{"name":{"type":"string"},"relation":{"type":"string"},"phone":{"type":"string"}},"required":["name","relation","phone"],"additionalProperties":false},"pay":{"description":"Only for keys with salaries:read.","type":"object","properties":{"basic":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"houseRent":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"conveyance":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"medical":{"type":"number","description":"An amount in the school's currency (PKR), as a number."},"gross":{"type":"number","description":"basic + allowances, a month."},"bank":{"type":"string"},"iban":{"type":"string"}},"required":["basic","houseRent","conveyance","medical","gross","bank","iban"],"additionalProperties":false}},"required":["id","code","firstName","lastName","gender","category","designation","department","campusId","employmentType","phone","email","cardNo","joinedOn","leftOn","status","updatedAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}},"description":"Needs the **staff:read** permission."}},"/pickups":{"get":{"operationId":"getPickups","tags":["Gate"],"summary":"The gate log","description":"Children handed over or refused at the gate between from and to (school days in the school's time zone; default today; at most 92 days), in id order.\n\nNeeds the **gate:read** permission.","x-permission":"gate:read","parameters":[{"name":"from","in":"query","required":false,"description":"First day (YYYY-MM-DD). Default: to.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"to","in":"query","required":false,"description":"Last day. Default: today.","schema":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},{"name":"studentId","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"result","in":"query","required":false,"schema":{"type":"string","enum":["handed","denied","override"]}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["pickup","drop"]}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"result":{"type":"string","description":"handed | denied | override (handed over although not authorised; note says why)"},"direction":{"type":"string","description":"pickup | drop"},"method":{"type":"string","description":"scan (QR card) | card-no (typed) | search | manual"},"offline":{"type":"boolean","description":"Checked on School360 Desktop without a connection."},"reason":{"description":"Why it was refused (denied).","type":["string","null"]},"note":{"type":["string","null"]},"studentId":{"type":["number","null"]},"campusId":{"type":["number","null"]},"collector":{"anyOf":[{"type":"object","properties":{"id":{"type":["number","null"]},"name":{"type":"string"},"kind":{"type":["string","null"]},"vehicleNo":{"type":["string","null"]}},"required":["id","name","kind","vehicleNo"],"additionalProperties":false},{"type":"null"}]}},"required":["id","at","result","direction","method","offline","reason","note","studentId","campusId","collector"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}}},"/notices":{"get":{"operationId":"getNotices","tags":["Notices"],"summary":"List notices","description":"Notices in id order. status: live (up now), scheduled, expired, draft, or published (every published one).\n\nNeeds the **notices:read** permission.","x-permission":"notices:read","parameters":[{"name":"audience","in":"query","required":false,"schema":{"type":"string","enum":["everyone","staff","families","classes"]}},{"name":"status","in":"query","required":false,"description":"Default: every notice.","schema":{"type":"string","enum":["live","scheduled","expired","draft","published"]}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"description":"nextCursor from the previous page.","schema":{"type":"string","maxLength":300}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"category":{"type":"string","description":"A notice category of the school (School Life › Fields & Options)."},"audience":{"type":"string","enum":["everyone","staff","families","classes"],"description":"everyone | staff | families (students and parents) | classes (classIds)"},"classIds":{"type":"array","items":{"type":"number"}},"campusId":{"description":"null: every campus.","type":["number","null"]},"pinned":{"type":"boolean"},"ackRequired":{"type":"boolean","description":"Staff are asked to press Got it."},"status":{"type":"string","enum":["draft","published"]},"state":{"type":"string","enum":["draft","scheduled","live","expired"],"description":"Where it stands now."},"text":{"type":"string","description":"The notice as plain text (up to 5,000 characters)."},"publishFrom":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publishUntil":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","title","category","audience","classIds","campusId","pinned","ackRequired","status","state","text","publishFrom","publishUntil","publishedAt","createdAt"],"additionalProperties":false}},"nextCursor":{"description":"Pass as cursor to get the next page; null on the last page.","type":["string","null"]},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"postNotices","tags":["Notices"],"summary":"Post a notice","description":"Puts a notice on the board, as School Life › Notice Board does. publish: false keeps it a draft. With publishFrom in the future it goes up then. Staff it reaches get it in the bell, and the notice.published webhook fires when it goes live. A campus-limited key posts to its campus.\n\nNeeds the **notices:write** permission.","x-permission":"notices:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique key (8–100 characters) for this request: a retry with the same key gets the first answer instead of doing it twice.","schema":{"type":"string","minLength":8,"maxLength":100}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"text":{"type":"string","minLength":1,"maxLength":20000,"description":"The notice. A blank line starts a new paragraph."},"category":{"type":"string","minLength":1,"maxLength":40,"description":"A notice category of the school, e.g. general, holiday, exam."},"audience":{"default":"everyone","description":"everyone | staff | families (students and parents) | classes (classIds)","type":"string","enum":["everyone","staff","families","classes"]},"classIds":{"description":"With audience classes.","maxItems":200,"type":"array","items":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"campusId":{"description":"Only this campus (default: every campus; a campus key: its campus).","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"pinned":{"default":false,"type":"boolean"},"ackRequired":{"default":true,"description":"Ask staff to press Got it.","type":"boolean"},"publish":{"default":true,"description":"false: save as a draft.","type":"boolean"},"publishFrom":{"description":"Go up later (ISO date-time).","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"publishUntil":{"description":"Come down then.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["title","text","category"]}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"number"},"title":{"type":"string"},"category":{"type":"string","description":"A notice category of the school (School Life › Fields & Options)."},"audience":{"type":"string","enum":["everyone","staff","families","classes"],"description":"everyone | staff | families (students and parents) | classes (classIds)"},"classIds":{"type":"array","items":{"type":"number"}},"campusId":{"description":"null: every campus.","type":["number","null"]},"pinned":{"type":"boolean"},"ackRequired":{"type":"boolean","description":"Staff are asked to press Got it."},"status":{"type":"string","enum":["draft","published"]},"state":{"type":"string","enum":["draft","scheduled","live","expired"],"description":"Where it stands now."},"text":{"type":"string","description":"The notice as plain text (up to 5,000 characters)."},"publishFrom":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publishUntil":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"publishedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"createdAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]}},"required":["id","title","category","audience","classIds","campusId","pinned","ackRequired","status","state","text","publishFrom","publishUntil","publishedAt","createdAt"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"}}}},"/changes":{"get":{"operationId":"getChanges","tags":["Changes"],"summary":"What changed since","description":"A polling feed for tools without webhooks (Zapier, Google Sheets, a nightly sync): the records added, changed or deleted since your cursor, oldest first, only those the key may read (and on its campus). Start without since to get a cursor for now; then call with since=nextCursor every few minutes, and again straight away while hasMore is true. nextCursor is always given: keep the last one. A page may be empty while hasMore is true (changes the key can't see). Changes are kept 30 days: an older cursor is 409 cursor_expired (read the lists again, then poll from a new cursor). Staff, exams, notices and the gate log aren't in the feed: use their lists (staff and students take updatedSince) or webhooks. Any key can read this.","parameters":[{"name":"since","in":"query","required":false,"description":"nextCursor from the previous call. Leave out to start from now.","schema":{"type":"string","maxLength":300}},{"name":"limit","in":"query","required":false,"description":"How many records to return (1–200, default 50).","schema":{"default":50,"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"entity":{"type":"string","enum":["campuses","years","classes","sections","students","families","vouchers","receipts","registers","applications"],"description":"campuses, years, classes, sections (any key); students; families; vouchers, receipts (fees); registers (attendance: GET /attendance); applications (admissions)."},"id":{"type":"number"},"op":{"type":"string","enum":["changed","deleted"],"description":"changed: added or changed (read it again); deleted: gone."},"at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["entity","id","op","at"],"additionalProperties":false}},"nextCursor":{"type":"string","description":"Pass as since next time (always given)."},"hasMore":{"type":"boolean"}},"required":["data","nextCursor","hasMore"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"403":{"$ref":"#/components/responses/E403"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"s360_live_…","description":"An API key from School Setup › Integrations."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"A stable, machine-readable code, e.g. forbidden, invalid_request."},"message":{"type":"string","description":"What went wrong, in plain English."},"field":{"description":"The query parameter or body field at fault, when there is one.","type":["string","null"]}},"required":["code","message","field"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}},"responses":{"E400":{"description":"The request isn't valid (invalid_request, invalid_json, idempotency_key_required).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"No key, or the key isn't valid, was revoked or has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"The key lacks the permission, the school doesn't have the API (plan_required), the workspace is off, or the IP address isn't allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"Not found (or outside the key's campus).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"Conflict: a payment reference already recorded, the same Idempotency-Key still running, a locked mark sheet, or (GET /changes) cursor_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E422":{"description":"The request can't be done as it stands (e.g. more than is due, idempotency_mismatch).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"Rate limited: wait Retry-After seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}