SCEDULY REST API Documentation
Introduction
SCEDULY REST API provides a standardized interface for interacting with the SCEDULY system. Communication is performed via the HTTPS version of the HTTP protocol using standard GET and POST methods for data transfer. Requests and responses are formatted using the JSON format.
Authentication
SCEDULY REST API uses the HMAC-SHA256 method to calculate the request signature. Each request must contain a minimum of 3 parameters required for authentication: user, institutionID, signature.
* HTTP_REQUEST_METHOD: GET or POST
* institutionID: institution ID in the SCEDULY system
* RequestURI: requested resource (ex: "/users/tuitions")
* Date: CEST (UTC+2), in format YYYY-MM-DD HH:ii (current: 2025-02-08 03:39)
* CRLF: Carriage return (char(13)) + Line feed (char(10))
Signature calculation:
data = HTTP_REQUEST_METHOD + CRLF institutionID + CRLF RequestURI + CRLF Date signature = HMAC-SHA256(data, password)
* institutionID: institution ID in the SCEDULY system
* RequestURI: requested resource (ex: "/users/tuitions")
* Date: CEST (UTC+2), in format YYYY-MM-DD HH:ii (current: 2025-02-08 03:39)
* CRLF: Carriage return (char(13)) + Line feed (char(10))
Example in PHP:
$data = 'GET' . "\r\n" . '999' . "\r\n" . '/users/tuitions' . "\r\n" . '2022-12-31 23:59'; $signature = hash_hmac('sha256', $data, '1234'); //6408cd6a53e6ecbfaa026c9f823dc36712d3dc810d366851d310570425b6a60c
Limitations
1. Only 10 connections at a time are allowed. Retrieving data with more than 10 simultaneous (parallel/concurrent) connections is not permitted!
2. Synchronization frequency is maximum of once per day. Retrieving data in second/minute/hour interval is not permitted!
3. Requests with network transmission time of up to 59 seconds will be accepted 100% of the time. Requests that arrive 2 or more minutes after they are signed will not be processed.
4. Changes to the API are announced at least 30 days in advance.
* Retrieval of data contrary to 1. and 2. may lead to account suspension!
2. Synchronization frequency is maximum of once per day. Retrieving data in second/minute/hour interval is not permitted!
3. Requests with network transmission time of up to 59 seconds will be accepted 100% of the time. Requests that arrive 2 or more minutes after they are signed will not be processed.
4. Changes to the API are announced at least 30 days in advance.
* Retrieval of data contrary to 1. and 2. may lead to account suspension!
/programs
Retrieves study programs data.
Parameters:
Response:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
programID | int | No | Data request for individual document |
Example 1:
Request:https://api.sceduly.com/programs?user=test&institutionID=999&signature={signature_string}
Response:
{ "1": { "programID": "1", "parentProgramID": null, "uniqueID": "PID_1", "externalUniqueID": "111", "programName": "Physics", "type": "university", "level": "6", "performance": "full-time", "startYear": "2017", "versions": { "11": { "programID": "11", "parentProgramID": "1", "uniqueID": "PID_1", "externalUniqueID": "111", "programName": "Physics", "type": "university", "level": "6", "performance": "full-time", "startYear": "2019", } } } }
Example 2:
Request:https://api.sceduly.com/programs?programID=11&user=test&institutionID=999&signature={signature_string}
Response:
{ "11": { "programID": "11", "parentProgramID": "1", "uniqueID": "PID_1", "externalUniqueID": "111", "programName": "Physics", "type": "university", "level": "6", "performance": "full-time", "academicVocationalTitle": "Bachelor's degree (baccalaurea) / Bachelor's degree (baccalaureus) in physics", "provider": "University of Split, Faculty of Science", "providerInstitution": "University of Split, Faculty of Science", "providerAddress": "Ruđera Boškovića 33, 21000, Split, Hrvatska", "providerPhone1": "021234567", "providerPhone2": "", "providerEmail": "mail@mail.com", "providerWebsite": "www.pmfst.unist.hr", "coProvider": "", "participationFee": "8000.00", "practiceHours": null, "startYear": "2019", "_embedded": { "learningOutcomes": { "1": { "learningOutcomeID": "1", "objectID": "11", "uniqueID": "LO-1", "externalUniqueID": "", "content": "Learning outcome at the program study level." } }, "subjectGroups": { "123": { "groupID": "123", "moduleID": "0", "programID": "11", "groupName": "e.g. rules of enrolment", "semester": "1", "compulsory": "1", "subjects": { "99": { "subjectID": "99", "groupID": "123", "uniqueID": "MAT1", "externalUniqueID": "54321", "subjectName": "Mathematics 1", "hours": { "P": "30", "A": "30" }, "lecturers": { "666": { "userID": "666", "firstName": "John", "lastName": "Doe", "title": "Phd", "teachingTitle": "" } } } } } }, "modules": { "22": { "moduleID": "22", "programID": "11", "externalUniqueID": "112", "moduleName": "Astrophysics and elementary particle physics", "subjectGroups": { "456": { "groupID": "456", "moduleID": "22", "programID": "11", "groupName": "e.g. rules of enrolment", "semester": "3", "compulsory": "1", "subjects": { "88": { "subjectID": "88", "groupID": "456", "uniqueID": "MAT2", "externalUniqueID": "54322", "subjectName": "Mathematics 2", "hours": { "P": "30", "A": "30" }, "lecturers": { "666": { "userID": "666", "firstName": "John", "lastName": "Doe", "title": "Phd", "teachingTitle": "" } } } } } } } } } } }
/subjects
Retrieves subject syllabus.
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
subjectID | int | Yes | Data request for individual document |
programID | int | No | Filter lecturers by study program |
Example:
Request:https://api.sceduly.com/subjects?subjectID=99&user=test&institutionID=999&signature={signature_string}
Response:
{ "99": { "subjectID": "99", "uniqueID": "MAT1", "externalUniqueID": "54321", "externalUniqueID2": "", "department": "Department of Physics", "subjectName": "Mathematics 1", "ects": "6", "onlinePercentage": "0", "goal": "", "enrolmentRequirements": "none", "learningOutcomes": "", "syllabus": "1. Lorem ipsum dolor sit amet.", "weekSyllabus": "", "weekSyllabusNotes": "", "teachingType": { }, "studentObligations": "", "studentEvaluation": "", "studentEvaluationTables": "", "studentMonitoring": "", "requiredLiterature": { }, "supplementaryLiterature": "", "qualityAssurance": "", "additionalNotes": "", "i18n": { }, "hours": { "P": "30", "V": "30" }, "weekSyllabus": { }, "programs": { "11": "Physics" }, "lecturers": { "666": { "userID": "666", "firstName": "John", "lastName": "Doe", "title": "Phd", "teachingTitle": "" } } } }
/orderOfLectures
Retrieves the order of lectures.
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
groupID | int | No | Filter data by department @see /users/groups |
programID | int | No | Filter data by study program |
academicYear | int | No | Academic year (when not specified - default value: current year) |
Example:
Request:https://api.sceduly.com/orderOfLectures?user=test&institutionID=999&signature={signature_string}
Response:
[ { "20": { "0": { "1": { "199": { "programID": "20", "moduleID": "0", "semester": "1", "compulsory": "1", "groupID": "199", "subjectID": "123", "erasmus": "1", "_embedded": { "program": { programID : "20", programName : "Physics", externalUniqueID : "41" }, "module": { moduleID : null, moduleName : null }, "subject": { subjectID : "123", subjectName : "General Physics I", uniqueID : "GP1", externalUniqueID : "999" }, "lecturers": { "666": { "userID": "666", "firstName": "John", "lastName": "Doe", "title": "Phd", "teachingTitle": "" } } } } } } } } ]
/workloadPlans
Retrieves the workload plans for users.
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
academicYear | int | No | Academic year (when not specified - default value: current year) |
Example:
Request:https://api.sceduly.com/workloadPlans?academicYear=2023&user=test&institutionID=999&signature={signature_string}
Response:
{ "planID": "1", "year": "2023", "approved": "1", "subjects": { "1111": { "2222": { "3333": { "subjectID": "1111", "userID": "2222", "typeID": "3333", "factor": "2.00", "factor2": "5.40", "factor3": "3.20", "weight": "1.00", "repetitiveWeight": "1.00", "groups": "1.00", "hours": "55.0", "repetitiveGroups": "0.00", "repetitiveHours": "0.0", "note": "", "_embedded": { "subject": { "uniqueID": "A-FP", "externalUniqueID": "999999" }, "teachingTypes": { "label": "L", "name": "Lectures" } } } } } } }
/users
Retrieves a list of institution users from a specific group, e.g. students, lecturers, etc.
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
groupID | int | Yes (if userID is not specified) | @see /users/groups |
userID | int | No | The user ID |
Example:
Request:https://api.sceduly.com/users?user=test&institutionID=999&groupID=123&signature={signature_string}
Response:
[ { "userID": "123", "firstName": "Ivona", "lastName": "Ivić", "personIDNumber": "00123456789", "personAcademicIDNumber": "55456545654" }, { "userID": "124", "firstName": "Mate", "lastName": "Matić", "personIDNumber": 00987654321, "personAcademicIDNumber": "44789878987" } ]
/users/groups
Retrieves a list of user groups (students, lecturers, etc.).
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
Example:
Request:https://api.sceduly.com/users/groups?user=test&institutionID=999&signature={signature_string}
Response:
[ { "groupID": "1", "externalUniqueID": "", "groupName": "Administrator", "groupDescription": "", "isDepartment": 0, "canLecture": 0 }, { "groupID": "2", "externalUniqueID": "999", "groupName": "Lecturer", "groupDescription": , "isDepartment": 0, "canLecture": 1 } ]
/users/photo
User photo in jpg format.
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
userID | int | Yes | The user ID |
Example:
Request:https://api.sceduly.com/users/photo?user=test&institutionID=999&userID=123&signature={signature_string}
Response:
[PHOTO IN JPG FORMAT]
/users/tuitions
Retrieves a list of tuition fees for accounting purposes (invoices).
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
personIDNumber | string | No | Data request for individual person |
academicYear | int | No | Academic year (when not specified - default value: current year) |
Example:
Request:https://api.sceduly.com/users/tuitions?user=test&institutionID=999&signature={signature_string}
Response:
[ { "personIDNumber": "00123456789", "firstName": "Ivona", "lastName": "Ivić", "address": "Dioklecijanova 1, Split", "email": "iivic@uniname.hr", "tuition": "8000.0000" }, { "personIDNumber": "11123456788", "firstName": "Mate", "lastName": "Matić", "address": null, "email": "mmatic@uniname.hr", "tuition": "7000.0000" } ]
/timetable/overview
Retrieves a timetable data for specified date interval and location.
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
location | string | Yes | Location (subsidiary) |
startDate | string | No | yyyy-mm-dd (when not specified - default value: current month) |
endDate | string | No | yyyy-mm-dd (when not specified - default value: current month) |
Example:
Request:https://api.sceduly.com/timetable/overview?user=test&institutionID=999&location=pmf-split&startDate=2022-01-01&endDate=2022-01-31&signature={signature_string}
Response:
[ { "eventID": "213512", "startDate": "2022-01-16", "endDate": "2022-02-21", "startTime": "09:15", "endTime": "12:00", "repetition": "1", "subjectID": "999", "classroomID": "1", "teachingType": "P", "groupID": "988", "notes": "Guest lecturer", "_embedded": { "subject": { "uniqueID": "OE1", "externalUniqueID": "299999", "subjectName": "Osnove elektrotehnike I" }, "classroom": { "classroomName": "A1" }, "lecturers": { "666": { "eventID": "213512", "userID": "666", "firstName": "John", "lastName": "Doe", "title": "Phd", "teachingTitle": "" } }, "programs": { "123": { "0": { "eventID": "213512", "programID": "123", "moduleID": "0", "level": "6.0", "type": "university", "programName": "Physics", "moduleName": null, } } } } } ]
/timetable/holidays
Retrieves institution holidays.
Parameters:
Response:
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
user | string | Yes | Your Sceduly REST API username |
institutionID | int | Yes | Data request for specified institution |
signature | string | Yes | HMAC-SHA256 signature |
Example:
Request:https://api.sceduly.com/timetable/holidays?user=test&institutionID=999&location=pmf-split&signature={signature_string}
Response:
{ "2023-12-27": "Holidays", "2023-12-28": "Holidays", "2023-12-29": "Holidays", "2024-01-01": "New Year" }