Einführung in die REST API

Mit der REST API kannst du Abwesenheitsdaten lesen und schreiben, Kontingente verwalten und absentify mit anderen Systemen verbinden. Beginne mit dem Schnellstart oder richte Webhooks für Ereignisse ein.

​

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-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. 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.

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. Die vollständige Liste der Endpunkte und ihrer Request- und Response-Schemas steht im interaktiven API-Bereich dieser Dokumentation.