APIs - data exchange

This integration is used to transfer Data from WebUntis to your 3rd-Party-Application or the other way.

We provide APIs which follows the international OneRoster specification and we provide our own WebUntis specific APIs.

 

OneRoster APIs

 

It´s based on REST-Interfaces that are correspondig to the international OneRoster-Specification 1.1 from IMS Global.

OneRoster 1.1 is a standard for sharing roster data between different systems at a school. Here you can find more informations about the Specification: OneRoster v1.1 Final Specification

The following APIs are provided by WebUntis:

For further informations about the API and how to call it, please check the OneRoster-Specification above.

Attention:

• A class in OneRoster is not a "Class" in WebUntis! A class in OneRoster is equivalent to a lesson in WebUntis.
• OneRoster only knows users and no master data without a user. Therefore, only student or teacher data is transferred via these interfaces if corresponding users exist for it.
• Due to performance issues while reading all enrollments for an entire school, we decided to return only enrollments for the current schoolyear. Other enrollment-endpoints return enrollments independent from schoolyears.

 

Information: 

Within the specified attribute "userIds" we send the following IDs from WebUntis:

• "uuid": Hashed ID of a user.
• "id": Internal ID of the user.
• "external-user-id": External ID of the user.
• "person-id": Internal ID of the person (masterdata).
  • Is only unique within the role (e.g. a student and a teacher can have the same person-id)
• "external-person-id": External ID of the person (masterdata).
  • Is only unique within the role (e.g. a student and a teacher can have the same external-person-id)
• "short-name": Shortname of the person (masterdata).
  • Is only unique within the role (e.g. a student and a teacher can have the same short-name)
• "national-id": National unique Id of the person (masterdata)

We extend the following information using the metadata-attributes:

• User-information:
  • Sex (gender) (optional)
    
  • Birthdate (optional)
  • Usergroup: The usergroup from WebUntis
  • Userrole: The users role from WebUntis
• Class-information:
  • ID and name of the WebUntis-Classes (eg. "1A")
  • From- and to-date of the lesson.
  • Optional name of the lesson.

 

 

WebUntis APIs

Attention - Limits

The maximum number of data records that you can send to WebUntis via API is limited to a payload of 10MB.

Larger requests are rejected with HTTP 413. If you need to send more than 10MB of data, you must distribute the data over several calls.

 

Managing student masterdata

With these APIs you can manage student masterdata including class-assignments and user for the student.

There is currently no way to delete students via the API. This needs to be done manually in WebUntis.

You can find the YAML-specification down below under "openapi-extern-student-management-api_v3.yaml"

Current Version: v3 (v1 & v2 are deprecated)

Domain	Service Call	Endpoint
Student	getStudentV3	GET {{API_URL}}WebUntis/api/rest/extern/v3/students/{{id}}
	getStudentsV3	GET {{API_URL}}WebUntis/api/rest/extern/v3/students
	createStudentsV3	POST {{API_URL}}WebUntis/api/rest/extern/v3/students
	updateStudentsV3	PUT {{API_URL}}WebUntis/api/rest/extern/v3/students

 

 

Managing teacher masterdata

With these APIs you can manage teacher masterdata and their users.

There is currently no way to delete teachers via the API. This needs to be done manually in WebUntis/Untis.

You can find the YAML-specification down below under "openapi-extern-teacher-management-api_v1.yaml"

Current Version: v1

Domain	Service Call	Endpoint
Teacher	getTeacherById	GET {{API_URL}}WebUntis/api/rest/extern/v1/teachers/{{id}}
	getTeachers	GET {{API_URL}}WebUntis/api/rest/extern/v1/teachers
	createTeachers	POST {{API_URL}}WebUntis/api/rest/extern/v1/teachers
	updateTeachers	PUT {{API_URL}}WebUntis/api/rest/extern/v1/teachers

 

 

Managing legal guardian masterdata

With these APIs you can manage legal guardian masterdata and their users.

There is currently no way to delete teachers via the API. This needs to be done manually in WebUntis/Untis.

You can find the YAML-specification down below under "openapi-extern-legal-guardian-management-api_v1.yaml"

Current Version: v1

Domain	Service Call	Endpoint
Legal Guardian	getLegalGuardianById	GET {{API_URL}}WebUntis/api/rest/extern/v1/legal-guardians/{{id}}
	getLegalGuardians	GET {{API_URL}}WebUntis/api/rest/extern/v1/legal-guardians
	createLegalGuardians	POST {{API_URL}}WebUntis/api/rest/extern/v1/legal-guardians
	updateLegalGuardians	PUT {{API_URL}}WebUntis/api/rest/extern/v1/legal-guardians

 

 

Managing class masterdata

With these APIs you can manage class masterdata.

There is currently no way to delete classes via the API. This needs to be done manually in WebUntis.

You can find the YAML-specification down below under "openapi-extern-class-management-api_v2.yaml"

Current Version: v2 (v1 is deprecated)

Domain	Service Call	Endpoint
Class	getClassByIdV2	GET {{API_URL}}WebUntis/api/rest/extern/v2/classes/{{id}}
	getClassesV2	GET {{API_URL}}WebUntis/api/rest/extern/v2/classes
	createClassesV2	POST {{API_URL}}WebUntis/api/rest/extern/v2/classes
	updateClassesV2	PUT {{API_URL}}WebUntis/api/rest/extern/v2/classes

 

 

Reading up2date timetable

With this API you get all data needed to display a timetable. You can filter by resource (student, teacher, room, class or lesson) and it can include all periods or only changed periods.
It includes the current state and changes from the scheduling timetable.

You can find the YAML-specification down below under "openapi-extern-timetable_v2.yaml"

Current Version: v3

Domain	Service Call	Endpoint
Timetable	getTimetable	GET {{API_URL}}WebUntis/api/rest/extern/v1/timetable
Timetable	getTimetableV2	GET {{API_URL}}WebUntis/api/rest/extern/v2/timetable
Timetable	getTimetableV3	GET {{API_URL}}WebUntis/api/rest/extern/v3/timetable

 

 

Reading Class register student absences

With this APIs you can read the absences of students from the class register. The class register is an optional module!

Calculated totals and also the individual data are returned.

You can find the YAML-specification down below under "openapi-extern-classreg-absences-v1-api.yaml"

Current Version: v1

Domain	Service Call	Endpoint
Class register	getStudentAbsenceTimes	GET {{API_URL}}WebUntis/api/rest/extern/v1/classreg/students/absencetimes
Class register	getStudentLessonAbsences	GET {{API_URL}}WebUntis//api/rest/extern/v1/classreg/students/lessonabsences

 

 

Reading Exams and ExamTypes

With this API you can read ExamTypes and Exams.

You can find the YAML-specification down below under "openapi-extern-exam-api.yaml"

Current Version: v1

Domain	Service Call	Endpoint
Exams	getExams	GET {{API_URL}}WebUntis/api/rest/extern/v1/exam
Exams	getExamTypes	GET {{API_URL}}WebUntis/api/rest/extern/v1/exam-types

 

 

Reading lessons and their students

With this API you can read the lessons and the related students. The difference to the OneRoster-API is, that this API also returns students without having users.

You can find the YAML-specification down below under "openapi-extern-lesson-api.yaml"

Current Version: v1

Domain	Service Call	Endpoint
Lessons	getLessons	GET {{API_URL}}WebUntis/api/rest/extern/v1/lesson

 

Sending messages to users

With this API you can send messages to users. Messages can either be sent as the platform itself or as a user of the platform, depending on the given token.

You can find the YAML-specification down below under "openapi-extern-messages-api.yaml"

Current Version: v1

Domain	Service Call	Endpoint
Messages	messages	POST{{API_URL}}WebUntis/api/rest/extern/v1/messages