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.

Signature calculation:

data =	HTTP_REQUEST_METHOD + CRLF
	institutionID + CRLF
	RequestURI + CRLF
	Date

signature = HMAC-SHA256(data, password)
* 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-05-14 19:06)
* 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!

/programs

Retrieves study programs data.

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:
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:
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:
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:
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:
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:
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:
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:
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:
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"
}