Common API Concepts

Both OneRoster and Untis Platform API families share the same pagination, sorting, and filtering mechanism. Every list endpoint on the platform uses the OneRoster 1.1 specification for these operations — regardless of which API family you call.

Caution

Pagination is mandatory for client-side implementation. Even if an endpoint could return all results in a single response, you must implement pagination to handle growth in data volume over time.

---

Pagination

All list endpoints accept two query parameters:

Parameter	Description
limit	Maximum number of results to return per page
offset	Number of results to skip before returning data

Example — fetch the first 100 students:

GET {{API_URL}}/ims/oneroster/v1p1/students?limit=100&offset=0

Increment offset by your limit value to page through results. Continue until a response returns fewer items than the requested limit.

---

Sorting

Use the sort query parameter with a field name. Use the optional orderBy parameter to control direction (asc or desc). If orderBy is omitted, the sort order is implementation-dependent.

Ascending:

GET {{API_URL}}/ims/oneroster/v1p1/users?sort=familyName&orderBy=asc

Descending:

GET {{API_URL}}/ims/oneroster/v1p1/users?sort=familyName&orderBy=desc

---

Filtering

Use the filter query parameter to restrict a list endpoint to the records you need. A filter is made of conditions. A condition follows the pattern: field operator 'value'

GET {{API_URL}}/ims/oneroster/v1p1/users?filter=role='student'

Operators

Operator	Meaning	Example
=	equals	role='student'
!=	not equal	role!='student'
>	greater than	dateLastModified>'2025-01-01T00:00:00Z'
>=	greater than or equal	username>='M'
<	less than	username<'C'
<=	less than or equal	username<='C'
~	contains	familyName~'mann'

Values are always written in single quotes.

Combining two conditions

You can join two conditions with AND or OR:

Keyword	Record is returned when…
AND	both conditions match
OR	at least one condition matches

GET {{API_URL}}/ims/oneroster/v1p1/users?filter=username='John' AND role='student'

GET {{API_URL}}/ims/oneroster/v1p1/users?filter=role='student' OR role='teacher'

Maximum of two conditions

A filter can contain at most two conditions, joined by a single AND or OR. Filters with three or more conditions, or that mix AND and OR, are not supported.

Not supported: role='student' AND username<='C' AND active='true'

If you need more than two conditions, filter by the two most selective ones in the request and apply the remaining checks in your own code.

Spaces and special characters

The spaces around AND / OR and any special characters in values must be URL-encoded when you build the request (for example %20 for a space and %27 for '). Most HTTP clients do this automatically when you pass the filter as a query parameter.

Consult the OneRoster 1.1 specification for the complete filtering syntax.

---

Combining parameters

Pagination, sorting, and filtering can be combined in a single request:

GET {{API_URL}}/ims/oneroster/v1p1/users?filter=role='student'&sort=familyName&orderBy=asc&limit=50&offset=0

---

Reading data for a school year

Classes and students exist across several school years. Unless you scope your request, the list endpoints return data for all school years.

1. Determine the school year

Read the school years via the OneRoster Academic Sessions API. Each session contains its startDate and endDate. Its sourcedId is the same ID that the Untis Platform APIs use as schoolyearId.

GET {{API_URL}}/ims/oneroster/v1p1/academicSessions

Do not hard-code school year dates

Each school configures the start and end of its school years. They do not necessarily match the first and last day of school around the summer holidays. Always read them from the API.

2. Scope your requests

API	How to scope to a school year
Class Management	Filter on the schoolyearId field: filter=schoolyearId=<id>
Student Management	Use the schoolyearId query parameter. It restricts the returned classAssignments to the given school year.
Teacher Management	Teachers are not tied to a school year. Use entryDate and exitDate to determine whether a teacher is employed during the school year.

Example — fetch all classes of a school year:

GET {{API_URL}}/WebUntis/api/rest/extern/v2/classes?filter=schoolyearId=123&limit=100&offset=0

Note

Use schoolyearId rather than the from and to dates of a class. These dates are not limited by the start and end of the class’ school year.

---