Timetable API FAQ

Will the names of the booking person (as shown in Timetable Cards in the UI) also become available via the API?

Not planned at the moment

How can we get the start/end dates of a school year via API?

No API for external partners available.

Can we sync the whole tenant instead of individual entities, e.g. teachers?

Yes, by omitting the teacher-id and setting dateLastModifiedAfter to a very early date.

Are there recurring periods, or are all periods materialized?

All events are materialized (no recurring events).

How should double periods (i.e.,two periods grouped) be merged?

Double periods share the same LessonId but appear as two periods because they can be cancelled individually. Grouping internally is based on comparing many attributes:

Periods are equal if these attributes are equal:

lesson id
type
status
exam
classes
departments
resources 
student groups
students
subjects
rooms
teachers

What happens if one of the double lessons gets cancelled (e.g. substitution)?

Periods are shown separately, because e.g. teacher is not the same across all periods. No automatic regrouping.

Why is break duration not available via API?

It’s part of internal timetable configuration and not exposed externally.

Is there an API to get the school’s timezone?

No, timezone is always the school’s local timezone; no public endpoint.

Why does the Timetable API only return abbreviations for subjects, classes, and rooms?

Full names are available via other APIs (e.g. external Class API).

How are notes or information across multiple lessons stored?

In the UI, users can enter data collectively or for individual lessons. Entries in the first period overwrite others. In the DB the information is stored as per period.

Is there a Room API to query rooms directly?

No. Rooms must be queried via external IDs or indirectly via Lesson/Teacher API.

Why do we receive HTTP 403 errors when calling the Timetable API?

Due to missing permissions of the app. Solution: permissions were later added; reinstall the app.

How do we detect deleted periods?

Short answer: Call /api/rest/extern/v3/timetable/deleted-periods together with /api/rest/extern/v3/timetable, using the same dateLastModifiedAfter, and process the results atomically.

• The deleted-periods endpoint returns an array of deleted period IDs only (no metadata).

• It does not support timetable filters (departments, classes, etc.); apply filtering on your side after joining IDs with your data.

• Use the same dateLastModifiedAfter for both calls and advance it only if both succeed; otherwise retry to avoid desync.

• Fallback if you can’t call the endpoint: do a full reload (start/end range) and compute a diff on your side.

There are two potential cases:

1. Teacher was changed in substitution planning (=individual periods)
2. Teacher was changed in timetabling for the lesson (either for the whole schoolyear or a specific term)

Data in the API for #1 (Teacher was changed in substitution planning)
Here you always get the original teacher as REMOVED and the substituting teacher as REGULAR. 

Data in the API for #2 (Teacher was changed in timetabling)
How timetabling works and how the exchange between Untis Client and WebUntis works, we do not detect this as a "substitution" or "teacher change". Changing lessons / introducing a new term basically creates a new "clean slate". WebUntis will not know that "this was the previous teacher", it will just know "this now is the teacher in the lesson".

Short answer:
Period and Resource statuses are related, but they do not automatically change together. The behavior depends on the type of change.

What happens if a period changes its time?
WebUntis does not support “shifted” periods.

If a period changes its time:

• The original period is cancelled
• A new period is created
• Both periods are linked via "relatedPeriod". If there are multiple shifts only the last two periods are linked together

Result:

The period status changes (Original: Cancelled; New: Additional)
Resource statuses (e.g. rooms, teachers) remain unchanged (`regular`)

What happens if resources are added or removed from a period?
If a resource changes (e.g. room A is added, room B is removed):

• All resource changes are reported
• The period status changes, because the period was modified

Does a resource change always affect the period status?
Yes. Any resource change implies a period change.

Does a period change always affect resource status?
No. Period changes (e.g. time changes via cancel + recreate) do not automatically change resource statuses.

Summary:

Resource change → period status changes
Period change → resource status does not necessarily change
Time changes are modeled as cancel + recreate, not as updates