openapi: 3.0.2 info: title: Extern - API Documentation for student management description: > WebUntis API for extern usage of platform applications to manage student masterdata incl. class-assignment and userdata. (Currently WebUntis openapi-specification does not support client code generation). IMPORTANT: For Students the following fields need to be unique: - shortName - externKey For Users the following fields need to be unique: - name - externKey version: 1.0.0 contact: name: Untis GmbH url: http://www.untis.at email: support@untis.at paths: /api/rest/extern/v1/students: get: summary: get a list of students operationId: getStudents tags: - student parameters: - name: page in: query description: Page - contains values for limit and offset. required: true schema: type: object properties: limit: type: integer format: int32 offset: type: integer format: int32 - name: sorting in: query description: Sorting - contains values for sort and orderby. required: true schema: type: object properties: sort: type: string orderBy: enum: - asc - desc - name: filter in: query x-java-parameter-annotations: "@com.grupet.api.extern.postprocessing.filtering.FilterParam" description: Filter - the filter query e.g. . required: false schema: type: string responses: "200": description: OK content: application/json: schema: type: object x-no-field-selection: true required: - students properties: students: type: array items: type: object required: - forename - lastName - shortName properties: id: type: integer format: int64 dateLastModified: type: string format: date-time externKey: type: string pattern: ^[^<>|\[\]]*$ minLength: 0 maxLength: 100 description: External identifier of the student, it needs to be unique catalogNumber: type: integer format: int32 minimum: 0 maximum: 32767 description: A consecutive number for the students in a class, often given in the alphabetical order of the students surnames, that serves as an identification within the class. attestationRequirement: type: boolean description: Medical certificate required compulsorySchooling: type: boolean description: Marks a student if he/she is legally required to be in a school (often determined by age or a minimum of years a student hast to attend any school) or if the student is voluntarily attending a school. adult: type: boolean description: Student is of legal age active: type: boolean description: Marks the student as active or not, which means if the student is already at this school. forename: type: string minLength: 1 maxLength: 64 pattern: ^[^<>|\[\]{}]*$ description: Student first name lastName: type: string minLength: 1 maxLength: 100 pattern: ^[^<>|\[\]{}]*$ description: Student family name shortName: type: string minLength: 1 maxLength: 60 pattern: ^[^<>|\[\]{}]*$ description: Student short name. (e.g. combination of first and family name) needs to be unique gender: description: Student's gender type: string enum: - female - male - inter birthDate: type: string format: date description: Students birth date entryDate: type: string format: date description: The date when student started his education at the school exitDate: type: string format: date description: The date when student ended his education at the school text: type: string description: Free text field for additional information classAssignment: x-no-field-selection: true description: a class is either identified by classId or className properties: classId: type: integer format: int64 description: Id of the class classExternKey: type: string minLength: 0 maxLength: 100 description: External identifier of the class startDate: type: string format: date description: Start date of the student in the class className: type: string description: short name of the class (e.g. „1A“) address: properties: street: type: string maxLength: 100 description: Street city: type: string maxLength: 100 description: City postCode: type: string maxLength: 20 description: Post code country: type: string x-extra-annotation: - "@com.grupet.api.validator.annotations.ValidI\ soCountryCode" description: Country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) email: type: string format: email maxLength: 255 description: Email adress phone: type: string maxLength: 50 pattern: "[0-9 +/-]+|^$" description: Phone number mobile: type: string maxLength: 50 pattern: "[0-9 +/-]+|^$" description: Mobile phone number fax: type: string maxLength: 50 pattern: "[0-9 +/-]+|^$" description: Fax number user: x-no-field-selection: true required: - name properties: id: type: integer format: int64 dateLastModified: type: string format: date-time name: type: string minLength: 1 maxLength: 128 pattern: ^[^<>|\[\]{}]*$ description: Username; needs to be unique externKey: type: string minLength: 0 maxLength: 100 pattern: ^[^<>|\[\]]*$ description: External identifier of the user; needs to be unique languageCode: type: string description: Language code for that user (https://de.wikipedia.org/wiki/ISO_639) email: type: string format: email maxLength: 255 description: Email of the user office365Id: type: string description: Identifier for office365 enabled: type: boolean default: true description: User is enabled or not externUuid: type: string readOnly: true description: External identifier for OneRoster studentAttributes: type: object additionalProperties: type: string description: Custom student attributes "400": description: Bad Request content: application/json: schema: type: object required: - errorCode - requestId - traceId - validationErrors properties: errorCode: type: string enum: - INTERNAL_ERROR - MASTER_DATA_NOT_FOUND - VALIDATION_ERROR - ENTITY_EXPIRED - MESSAGING_GROUP_CALCULATION_ERROR - MESSAGING_READ_CONFIRMATION_ALREADY_CONFIRMED - NOT_FOUND - FORBIDDEN - TT_ONGOING_TIMETABLE_PUBLICATION - TT_UNRESOLVED_CHANGESET - BAD_REQUEST requestId: type: string traceId: type: string validationErrors: type: array items: type: object required: - path - errorMessage properties: path: type: string errorMessage: type: string index: type: integer errorData: type: array items: type: object properties: id: type: integer format: int64 externKey: type: string "401": description: Unauthorized content: application/json: schema: type: object required: - errorCode - errorMessage - requestId - traceId properties: errorCode: type: string enum: - INTERNAL_ERROR - MASTER_DATA_NOT_FOUND - VALIDATION_ERROR - ENTITY_EXPIRED - MESSAGING_GROUP_CALCULATION_ERROR - MESSAGING_READ_CONFIRMATION_ALREADY_CONFIRMED - NOT_FOUND - FORBIDDEN - TT_ONGOING_TIMETABLE_PUBLICATION - TT_UNRESOLVED_CHANGESET - BAD_REQUEST errorMessage: type: string requestId: type: string traceId: type: string "403": description: Forbidden content: application/json: schema: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/401/content/appl\ ication~1json/schema" "404": description: Not Found content: application/json: schema: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/400/content/appl\ ication~1json/schema" "500": description: Internal Server Error content: application/json: schema: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/401/content/appl\ ication~1json/schema" post: summary: Import a list of students operationId: createStudents tags: - student responses: "200": description: OK - If all sent students are imported succsesfully content: application/json: schema: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema" "400": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/400" "401": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/401" "403": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/403" "404": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/404" "500": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/500" requestBody: description: Contains a list of students that will be imported required: true content: application/json: schema: type: object x-no-field-selection: true required: - students properties: students: type: array items: type: object required: - forename - lastName - shortName properties: id: type: integer format: int64 dateLastModified: type: string format: date-time externKey: type: string pattern: ^[^<>|\[\]]*$ minLength: 0 maxLength: 100 description: External identifier of the student, it needs to be unique catalogNumber: type: integer format: int32 minimum: 0 maximum: 32767 description: A consecutive number for the students in a class, often given in the alphabetical order of the students surnames, that serves as an identification within the class. attestationRequirement: type: boolean description: Medical certificate required compulsorySchooling: type: boolean description: Marks a student if he/she is legally required to be in a school (often determined by age or a minimum of years a student hast to attend any school) or if the student is voluntarily attending a school. adult: type: boolean description: Student is of legal age active: type: boolean description: Marks the student as active or not, which means if the student is already at this school. forename: type: string minLength: 1 maxLength: 64 pattern: ^[^<>|\[\]{}]*$ description: Student first name lastName: type: string minLength: 1 maxLength: 100 pattern: ^[^<>|\[\]{}]*$ description: Student family name shortName: type: string minLength: 1 maxLength: 60 pattern: ^[^<>|\[\]{}]*$ description: Student short name. (e.g. combination of first and family name) needs to be unique gender: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema/properties/students/items/proper\ ties/gender" birthDate: type: string format: date description: Students birth date entryDate: type: string format: date description: The date when student started his education at the school exitDate: type: string format: date description: The date when student ended his education at the school text: type: string description: Free text field for additional information classAssignment: x-no-field-selection: true description: a class is either identified by classId or className properties: classId: type: integer format: int64 description: Id of the class classExternKey: type: string minLength: 0 maxLength: 100 description: External identifier of the class startDate: type: string format: date description: Start date of the student in the class className: type: string description: short name of the class (e.g. „1A“) address: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema/properties/students/items/proper\ ties/address" user: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema/properties/students/items/proper\ ties/user" studentAttributes: type: object additionalProperties: type: string description: Custom student attributes put: summary: Update a list of students operationId: updateStudents description: > The following fields can be used to identify a student (ordered hierarchically) - id, externKey The following fields can be used to identify a student-user (ordered hierarchically) - user.externUuid, user.externKey, user.name If the student does not yet have a user, it is created. tags: - student responses: "200": description: OK - If all sent students are updated succsesfully content: application/json: schema: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema" "400": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/400" "401": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/401" "403": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/403" "404": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/404" "500": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/500" requestBody: description: Contains a list of students that will be updated required: true content: application/json: schema: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/post/requestBody/content/appli\ cation~1json/schema" "/api/rest/extern/v1/students/{studentId}": get: summary: get a student operationId: getStudentById tags: - student parameters: - in: path name: studentId required: true description: The id of the student to retrieve schema: type: string responses: "200": description: OK content: application/json: schema: type: object required: - forename - lastName - shortName properties: id: type: integer format: int64 dateLastModified: type: string format: date-time externKey: type: string pattern: ^[^<>|\[\]]*$ minLength: 0 maxLength: 100 description: External identifier of the student, it needs to be unique catalogNumber: type: integer format: int32 minimum: 0 maximum: 32767 description: A consecutive number for the students in a class, often given in the alphabetical order of the students surnames, that serves as an identification within the class. attestationRequirement: type: boolean description: Medical certificate required compulsorySchooling: type: boolean description: Marks a student if he/she is legally required to be in a school (often determined by age or a minimum of years a student hast to attend any school) or if the student is voluntarily attending a school. adult: type: boolean description: Student is of legal age active: type: boolean description: Marks the student as active or not, which means if the student is already at this school. forename: type: string minLength: 1 maxLength: 64 pattern: ^[^<>|\[\]{}]*$ description: Student first name lastName: type: string minLength: 1 maxLength: 100 pattern: ^[^<>|\[\]{}]*$ description: Student family name shortName: type: string minLength: 1 maxLength: 60 pattern: ^[^<>|\[\]{}]*$ description: Student short name. (e.g. combination of first and family name) needs to be unique gender: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema/properties/students/items/properties\ /gender" birthDate: type: string format: date description: Students birth date entryDate: type: string format: date description: The date when student started his education at the school exitDate: type: string format: date description: The date when student ended his education at the school text: type: string description: Free text field for additional information classAssignment: x-no-field-selection: true description: a class is either identified by classId or className properties: classId: type: integer format: int64 description: Id of the class classExternKey: type: string minLength: 0 maxLength: 100 description: External identifier of the class startDate: type: string format: date description: Start date of the student in the class className: type: string description: short name of the class (e.g. „1A“) address: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema/properties/students/items/properties\ /address" user: $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/200/content/appl\ ication~1json/schema/properties/students/items/properties\ /user" studentAttributes: type: object additionalProperties: type: string description: Custom student attributes "400": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/400" "401": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/401" "403": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/403" "404": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/404" "500": $ref: "#/paths/~1api~1rest~1extern~1v1~1students/get/responses/500"