> ## Documentation Index
> Fetch the complete documentation index at: https://absentify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Einführung in die REST API
> Nutze die absentify REST API für Abwesenheitsanfragen, Kontingente, Benutzer, Abteilungen und Webhooks.
Mit der REST API kannst du Abwesenheitsdaten lesen und schreiben, Kontingente verwalten und absentify mit anderen Systemen verbinden. Beginne mit dem [Schnellstart](./quick_start) oder richte [Webhooks](./webhooks) für Ereignisse ein.
Die API erfordert den Plus-Plan. Das enthaltene Limit beträgt 150 Anfragen pro Sekunde und IP-Adresse. Für ein kostenpflichtiges Limit von 1500 Anfragen pro Sekunde erhältst du die aktuellen Preise beim Support.
## Lokalisierte Namen
Endpunkte mit Abwesenheitsart- oder Kontingentnamen akzeptieren optional `locale` (`en`, `de`, `fr`, `hu`, `it`, `pl`, `pt`, `ru`, `es`, `tr` oder `uk`). Bei GET-Anfragen ist dies ein Query-Parameter. `name` verwendet die Übersetzung, falls vorhanden; `default_name` enthält immer den gespeicherten Namen. Nicht unterstützte Werte wie `DE` oder `de-DE` geben `400` zurück.
Ohne `locale` bleiben Namen von Abwesenheitsarten unverändert. Kontingentnamen folgen der Sprache des Benutzers, dem der API-Schlüssel gehört. Bei `GET /requests_per_day` werden außerdem `month`, `weekday` und `fullday` lokalisiert. Aktuelle [Webhook](./webhooks)-Payloads liefern nur den gespeicherten Namen.
`POST /leave_types` und `PUT /leave_types/{id}` akzeptieren optional ein Array `translations` mit Objekten `{ language, name }`. Wenn du es sendest, ersetzt es alle gespeicherten Übersetzungen. Lässt du das Feld weg, bleiben sie unverändert.
## Kontingente über die API verwalten
Eine Kontingentregel bestimmt Betrag, Rhythmus, Beginn des Kontingentjahres und Übertrag. Eine Regel gehört zu einer Kontingentart. Benutzer werden über eine Regelzuweisung mit Gültigkeitszeitraum verbunden; individuelle Korrekturen werden als Anpassungen gespeichert.
| Zweck | Endpunkte |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Kontingentarten | `GET`/`POST /allowance-types`, `GET`/`PATCH`/`DELETE /allowance-types/{id}`, `POST /allowance-types/reorder`, `PUT /allowance-types/{allowance_type_id}/default-rule` |
| Regeln | `GET`/`POST /allowance-types/{allowance_type_id}/rules`, `PATCH`/`DELETE /rules/{id}`, `GET /rules/{rule_id}/members` |
| Regelzuweisungen | `GET`/`POST /members/{member_id}/rule-assignments`, `PATCH`/`DELETE /rule-assignments/{id}`, `POST /members/{member_id}/rule-change`, `POST /members/{member_id}/manual-rule` |
| Anpassungen | `GET`/`POST /members/{member_id}/adjustments`, `DELETE /adjustments/{id}` |
| Salden | `GET /members/{member_id}/allowances`, `GET /members/{member_id}/allowance-breakdown`, `POST /allowances/{id}/revert-carryover-override` |
| Historie | `GET /rules/{rule_id}/audit-log`, `GET /allowance-types/{allowance_type_id}/audit-log`, `GET /members/{member_id}/rule-audit-log`, `GET /members/{member_id}/allowance-audit-log` |
Beachte dabei:
* Schreibzugriffe auf die Kontingentverwaltung erfordern einen authentifizierten Administrator. Die Leseendpunkte `GET /allowance-types`, `GET /allowance-types/{id}` und `GET /members/{member_id}/allowances` funktionieren auch im Kontext eines authentifizierten Managers für Benutzer, die er sehen darf. Workspace-API-Schlüssel können nur aktive Administratoren erstellen und verwenden; ein Manager-Kontext kann über ein validiertes Microsoft Entra ID Bearer-Token entstehen.
* `GET /allowance-types` liefert die IDs, die Regeln, Zuweisungen, Anpassungen und Salden als `allowance_type_id` verwenden. Jede Kontingentart enthält außerdem `default_rule_id` und `default_rule_manually_managed`. Ist `default_rule_manually_managed` wahr, werden neue Benutzer manuell verwaltet, sofern ihre Abteilung keine Regel vorgibt.
* Datumsfelder wie `rule_start_date`, `rule_end_date`, `accrual_anchor_date`, `date` und `expiry_date` verwenden `YYYY-MM-DD`.
* `rule_start_date` ist der erste eingeschlossene Tag. `rule_end_date` und `expiry_date` sind der letzte eingeschlossene Tag. `null` bedeutet kein Enddatum.
* `coverage_start_date` ist schreibgeschützt und zeigt den tatsächlichen Beginn des Kontingentaufbaus für den Benutzer.
* `coverage_start_date` entspricht `rule_start_date` oder dem späteren Beschäftigungsbeginn. Ohne Beschäftigungsbeginn, bei einer früher begonnenen Beschäftigung oder wenn die Zuweisung schon vorher endete, bleibt es bei `rule_start_date`. Eine spätere Korrektur des Beschäftigungsbeginns ändert `coverage_start_date` beim nächsten Lesen, nicht `rule_start_date`.
* Bei `PATCH /rule-assignments/{id}` lässt ein nicht gesendetes `rule_end_date` den Wert unverändert; `null` macht die Zuweisung unbegrenzt.
* Das `expiry_date` einer Anpassung ist der letzte nutzbare Tag. Es darf dem Datum der Anpassung entsprechen; ein früheres Datum wird abgelehnt.
* Beträge verwenden Tage für tagesbasierte und Minuten für stundenbasierte Kontingente.
* `proration_basis` steuert die Berechnung eines anteiligen Jahres: `month` zählt volle Monate vollständig und berechnet angebrochene Start- oder Endmonate taggenau, `day` rechnet jeden Kalendertag und `full_month` zählt nur vollständige Monate mit jeweils 1/12. Der Standard ist `month`; bei monatlichen und zweiwöchentlichen Regeln wird das Feld ignoriert.
* `rule_amount` muss größer als 0 sein. Nutze `POST /members/{member_id}/manual-rule`, wenn kein automatischer Aufbau stattfinden soll.
* Änderungen und Löschungen von Zuweisungen benötigen einen Grund mit 3 bis 500 Zeichen.
* `GET /members/{member_id}/allowances` liefert `allowance` als wirksames Kontingent, aufgeteilt in `rule_allowance` und `adjustments`.
### Ketten von Regelzuweisungen
Zuweisungen für eine Kontingentart bilden eine Kette. Ein Enddatum (`rule_end_date` oder `valid_until`) ist nur am Tag vor dem Beginn der nächsten Zuweisung oder am letzten Beschäftigungstag zulässig. Verwende `null`, wenn nichts folgt. Bereits vorhandene Lücken oder Überschneidungen werden toleriert, dürfen durch einen Schreibzugriff aber nicht größer werden. Beim Löschen einer Zuweisung erweitert absentify die vorherige Zuweisung nach vorn oder, falls es keine gibt, die folgende nach hinten.
### Kontingentarten und Standards
* `POST /allowance-types` erstellt eine Kontingentart ohne Regel. Bis du eine Regel hinzufügst, wird nichts gutgeschrieben.
* `allowance_unit` ist `days` oder `hours` und kann nach der Erstellung nicht geändert werden. Stundenbasierte Beträge werden in Minuten angegeben.
* `PATCH /allowance-types/{id}` ändert nur übermittelte Felder. `translations` ersetzt beim Senden den gesamten gespeicherten Satz.
* `DELETE /allowance-types/{id}` ist gesperrt, solange Abwesenheitsarten, Standardzuweisungen oder Regeln davon abhängen und für die letzte Kontingentart im Workspace.
* `POST /allowance-types/reorder` setzt die Reihenfolge. Sende für ein eindeutiges Ergebnis alle IDs des Workspaces.
* `PUT /allowance-types/{allowance_type_id}/default-rule` setzt den Organisationsstandard für neue Benutzer. `rule_id: null` wählt **Manuell verwalten**. Eine Regel muss aktiv, geteilt und von derselben Kontingentart sein. Bestehende Benutzer werden nicht verschoben; ein Abteilungsstandard hat für neue Benutzer Vorrang.
* `DELETE /rules/{id}` benötigt `reassign_to`, solange Benutzer zugewiesen sind. Sie bleiben bis zum ersten Geschäftsjahresbeginn ab heute auf der gelöschten Regel und wechseln dann, niemals mitten im Jahr.
### Benutzer zwischen Regeln verschieben
* `POST /members/{member_id}/rule-change` beendet die aktuelle Zuweisung am Tag vor `valid_from` und beginnt die neue an `valid_from`. Sende die ersetzte Zuweisung als `current_assignment_id`.
* `POST /members/{member_id}/manual-rule` beendet den automatischen Aufbau ab `valid_from`. Sende die aktive Zuweisung als `current_assignment_id`, oder `null`, wenn keine besteht. Eine überlappende Zuweisung führt sonst zum Fehler.
* `valid_from` ist der erste eingeschlossene, `valid_until` der letzte eingeschlossene Tag. `valid_until: null` bedeutet unbegrenzt. Beide Endpunkte verlangen einen Grund mit 3 bis 500 Zeichen.
* `GET /rules/{rule_id}/members` ist eine Vorschau ohne Offset: `limit` ist 1 bis 50, Standard 10, während `total` alle zugewiesenen Benutzer zählt.
### Salden und Historie lesen
* `GET /members/{member_id}/allowances` liefert alle verfügbaren Geschäftsjahre aufsteigend. `allowance` entspricht `rule_allowance` plus `adjustments`; deaktivierte Kontingentarten fehlen.
* `GET /members/{member_id}/allowance-breakdown` erklärt Regel, monatliche Gutschriften, Übertrag, Verfall und gebuchte Anfragen. Bei `legacy_unmigrated` oder `no_allowance_for_year` bleiben die übrigen Details leer.
* `POST /allowances/{id}/revert-carryover-override` entfernt einen manuell gesetzten Übertrag. Der zurückgegebene Wert `brought_forward` ist der Wert **vor** dem Zurücksetzen. Lies danach die Kontingente erneut, um den neu berechneten Wert zu erhalten.
* `GET /rules/{rule_id}/audit-log`, `GET /allowance-types/{allowance_type_id}/audit-log`, `GET /members/{member_id}/rule-audit-log` und `GET /members/{member_id}/allowance-audit-log` liefern neueste Einträge zuerst. Regel- und Kontingentart-Logs akzeptieren `take` von 1 bis 200, Standard 100; Benutzerhistorien liefern höchstens 200 Einträge.
* `changes` hängt vom `event_type` ab: Eine Regeländerung enthält `{ field: { from, to } }`, ein Regelwechsel `from_rule_id` und `to_rule_id`. Das Löschen einer Regel mit Benutzern enthält `reassigned_to` oder `reassigned_to_manual` sowie `effective_from`.
* Ein Regelwechsel steht bei der neuen Regel und enthält `from_rule_id`. Gelöschte Regeln behalten ihre Historie, die dann nur noch im Audit-Log der Kontingentart erreichbar ist.
`PUT /members/{id}/allowance/{allowance_type_id}/{year}` ist veraltet. Nutze Regeln und Anpassungen für neue Integrationen.
Bei einem Benutzer mit Regel ist `allowance` in diesem veralteten Endpunkt der absolute Zielwert für das Jahr. absentify speichert die Differenz zur Regel als eine wiederverwendete Anpassung **Über API festgelegt**. Gleiche Werte erzeugen keinen neuen Eintrag; der Regelbetrag entfernt diese Anpassung. Andere manuelle Anpassungen bleiben zusätzlich bestehen. Ohne Regel hat `allowance` in einem bereits konvertierten Workspace keine Wirkung. `brought_forward`, `compensatory_time_off`, `set_as_default` und `disabled` funktionieren weiterhin. Ein nicht gesendetes Feld behält seinen Wert, einschließlich `overwrite_brought_forward`. Während einer Migration oder nach einem Rollback wird die ganze Anfrage mit einem Konflikt abgelehnt; ein nicht abgedecktes Jahr gibt `404` zurück.
**Geändert am 10. August 2026:** `rule_end_date` wurde früher als erster nicht mehr gültiger Tag gelesen. Heute ist es der letzte eingeschlossene Gültigkeitstag. Wenn deine Integration zum Ausgleich einen Tag addiert hat, entferne diese Anpassung.
Die vollständige Liste der Endpunkte und ihrer Request- und Response-Schemas steht im interaktiven API-Bereich dieser Dokumentation.