Timebutler API v2

Persönliche Zugangstoken

Als Alternative zum OAuth-2.0-Passwort-Flow können einzelne Benutzer persönliche Zugangstoken anlegen. Die Token sind langlebig, benannt, einzeln widerrufbar und auf einen Benutzer beschränkt — kein Passwort-Sharing und kein Refresh-Token-Wechsel nötig.

Token haben das Präfix tb_ gefolgt von einem undurchsichtigen, URL-sicheren Base64-String. Sie werden im Authorization-Header übergeben, genau wie ein normales Bearer-Token:

curl "https://app.timebutler.com/api/v2/timeentry/pendingcount" \
  -H "Authorization: Bearer tb_a1b2c3d4e5f6..."

Persönliches Token erstellen oder widerrufen →

Token ausstellen oder erneuern

Unterstützt fünf Grant-Typen: **`grant_type=password`** — Authentifizierung mit `username` und `password`. Bei Erfolg wird ein Zugriffstoken und ein Refresh-Token zurückgegeben. Falls das Konto 2FA aktiviert hat, wird stattdessen eine MFA-Anforderung zurückgegeben (`mfa_required=true`, `mfa_token`, `mfa_expires_in`) — den Ablauf mit `grant_type=mfa_totp` abschließen. **`grant_type=refresh_token`** — Tauscht ein gültiges `refresh_token` gegen ein neues Zugriffstoken aus und rotiert das Refresh-Token (jedes Refresh-Token kann nur einmal verwendet werden). **`grant_type=mfa_totp`** — Zweiter Schritt des 2FA-Ablaufs. Den `mfa_token` aus der Passwort-Grant-Anforderung zusammen mit dem aktuellen `totp_code` aus der Authenticator-App des Benutzers übermitteln. Bei Erfolg werden Zugriffstoken und Refresh-Token zurückgegeben. **`grant_type=sso_id_token`** — Single Sign-On mit einem ID-Token, das die mobile App bereits vom SSO-Anbieter erhalten hat. `provider=google` und das vom Anbieter ausgestellte `id_token` (ein JWT) übermitteln. Timebutler prüft Signatur, Aussteller und Zielgruppe des JWT und gibt für das verknüpfte Timebutler-Konto Zugriffs- und Refresh-Token zurück. **`grant_type=sso_code`** — Single Sign-On mit einem Authorization Code, den die mobile App vom Consent-Screen des SSO-Anbieters erhalten hat. `provider=microsoft` oder `provider=slack`, den `code` vom Anbieter sowie die in der Authorize-Anfrage verwendete `redirect_uri` übermitteln. Bei Microsoft-Public-Client-App-Registrierungen zusätzlich den PKCE-`code_verifier` senden, dessen SHA-256-Hash als `code_challenge` im Authorize-Schritt verwendet wurde. Timebutler tauscht den Code beim Anbieter ein, identifiziert den Benutzer und gibt das Token-Paar zurück. Alle Grant-Typen erfordern außerdem `client_id`. Verwende `client_id=public` zur Authentifizierung ohne Secret, oder übergib `client_id` und `client_secret` für einen registrierten vertraulichen Client.

Name	Typ	Description
grant_type	string	OAuth-2.0-Grant-Typ. Unterstützte Werte: `password`, `refresh_token`, `mfa_totp`, `sso_id_token`, `sso_code`.
username	string	E-Mail-Adresse des Benutzers. Erforderlich für `grant_type=password`.
password	string	Passwort des Benutzers. Erforderlich für `grant_type=password`.
refresh_token	string	Refresh-Token aus einer vorherigen Token-Antwort. Erforderlich für `grant_type=refresh_token`.
client_id	string	Client-Bezeichner. Verwende `public` für nicht authentifizierte öffentliche Clients.
client_secret	string	Client-Secret. Erforderlich für vertrauliche Clients; weglassen bei `client_id=public`.
mfa_token	string	MFA-Challenge-Token, das bei einem `password`-Grant zurückgegeben wird, wenn 2FA erforderlich ist. Erforderlich für `grant_type=mfa_totp`.
totp_code	string	Aktueller TOTP-Code aus der Authenticator-App des Benutzers. Erforderlich für `grant_type=mfa_totp`.
provider	string	SSO-Anbieter-Bezeichner. Erforderlich für `grant_type=sso_id_token` (`google`) und `grant_type=sso_code` (`microsoft`, `slack`).
id_token	string	Vom Anbieter ausgestelltes SSO-ID-Token (z. B. ein Google-ID-Token-JWT). Erforderlich für `grant_type=sso_id_token`.
code	string	Vom Authorize-Endpunkt des SSO-Anbieters zurückgegebener Authorization Code. Erforderlich für `grant_type=sso_code`.
redirect_uri	string	Redirect-URI, die beim Abruf des Authorization Codes verwendet wurde. Muss mit dem beim SSO-Anbieter hinterlegten Wert übereinstimmen. Erforderlich für `grant_type=sso_code`.
code_verifier	string	PKCE-Code-Verifier — der Klartextwert, dessen SHA-256-Hash als `code_challenge` in der Authorization-Anfrage gesendet wurde. Erforderlich für `grant_type=sso_code`, wenn die App-Registrierung des SSO-Anbieters ein öffentlicher Client ist.

{ }

Name	Typ	Description
error	string	OAuth-2.0-Fehlercode (z. B. `invalid_grant`, `invalid_client`).
error_description	string	Menschenlesbare Fehlerbeschreibung.

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

Name	Typ	Description
error	string	OAuth-2.0-Fehlercode (z. B. `invalid_grant`, `invalid_client`).
error_description	string	Menschenlesbare Fehlerbeschreibung.

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

Name	Typ	Description
error	string	OAuth-2.0-Fehlercode (z. B. `invalid_grant`, `invalid_client`).
error_description	string	Menschenlesbare Fehlerbeschreibung.

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

Name	Typ	Description
error	string	OAuth-2.0-Fehlercode (z. B. `invalid_grant`, `invalid_client`).
error_description	string	Menschenlesbare Fehlerbeschreibung.

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

curl -X POST "https://app.timebutler.com/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=password&username=user%40example.com&password=s3cr3t&client_id=public'

curl -X POST "https://app.timebutler.com/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=refresh_token&refresh_token=550e8400-e29b-41d4-a716-446655440000&client_id=public'

curl -X POST "https://app.timebutler.com/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=mfa_totp&mfa_token=mfa-a1b2c3d4e5f6&totp_code=123456&client_id=public'

Offenen Abwesenheitsantrag genehmigen

Vermerkt die Genehmigung des Aufrufers auf einem Antrag im Zustand `pending`. Hat der Mitarbeiter mehrere Manager, wechselt der Antrag erst dann in `approved`, wenn alle Manager genehmigt haben (oder ein Administrator genehmigt). Der Aufrufer muss Administrator oder direkter Vorgesetzter des Antragstellers sein.

Name	Typ	Description
iderforderlich	integer(int32)	Interne ID des zu genehmigenden Abwesenheitsantrags.

Name	Typ	Description
id	string	Interne ID des Abwesenheitsantrags.
type	string	Abwesenheitstyp-Code (3 Zeichen), z. B. `"URL"` für Urlaub.
startDate	string	Erster Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Letzter Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst, berechnet gemäß dem Arbeitszeitplan des Mitarbeiters.
status	string	Aktueller Status des Antrags. Einer von `pending` (wartet auf Genehmigung), `approved` oder `rejected`. Mögliche Werte: pending approved rejected
halfDay	string	Halbtags-Indikator. `"morning"` oder `"afternoon"` für Halbtagsanträge; `null` für ganztägige Abwesenheiten. Mögliche Werte: morning afternoon
substitutePending	boolean	Ob die Bestätigung des Vertreters noch aussteht. `null`, wenn kein Vertreter gesetzt wurde.
medicalCertificateProvided	boolean	Ob ein Attest für diese Abwesenheit hochgeladen wurde. Nur vorhanden bei Abwesenheitstypen, die ein Attest erfordern; sonst `null`.
employeeName	string	Anzeigename des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.
employeeId	string	Interne ID des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X POST "https://app.timebutler.com/api/v2/absence-requests/{id}/approve" \
  -H "Authorization: Bearer <token>"

Eigene Abwesenheitsanträge des Aufrufers auflisten (Alias)

Alias-Endpunkt, der dasselbe Ergebnis wie `GET /my` liefert. In neuen Integrationen `/my` bevorzugen — dieser Pfad existiert aus Gründen der Abwärtskompatibilität.

[ {
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-requests" \
  -H "Authorization: Bearer <token>"

Neuen Abwesenheitsantrag erstellen

Reicht einen neuen Abwesenheits- oder Urlaubsantrag für den Aufrufer ein. Der resultierende Status hängt von der Konfiguration des Abwesenheitstyps ab: Typen, die eine Genehmigung durch den Manager erfordern, starten mit `pending`, andernfalls gehen sie direkt auf `approved`. Datumsangaben sind ISO-8601 (`YYYY-MM-DD`). Bei Halbtagsanträgen `halfDay` auf `morning` oder `afternoon` setzen und denselben Wert für `startDate` und `endDate` verwenden.

Felder des neuen Abwesenheitsantrags.

Name	Typ	Description
absenceTypeIderforderlich	string	Abwesenheitstyp-Code (3 Zeichen), z. B. `"URL"` für Urlaub. Muss einem aktiven Typ aus `GET /absence-types` entsprechen.
startDateerforderlich	string	Erster Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDateerforderlich	string	Letzter Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`). Muss gleich oder nach `startDate` liegen. Bei Halbtagsanträgen muss es gleich `startDate` sein.
halfDay	string	Auf `"morning"` oder `"afternoon"` setzen, um einen einzelnen Halbtag zu beantragen. Wenn gesetzt, müssen `startDate` und `endDate` denselben Tag haben. Weglassen oder `null` senden für eine ganztägige Abwesenheit. Mögliche Werte: morning afternoon
comments	string	Optionaler Freitextkommentar, der den Managern des Mitarbeiters angezeigt wird.
substituteEmployeeId	string	Mitarbeiter-ID des designierten Vertreters. Muss zum selben Unternehmen gehören. Weglassen oder `null` senden, wenn kein Vertreter benötigt wird.

Name	Typ	Description
id	string	Interne ID des Abwesenheitsantrags.
type	string	Abwesenheitstyp-Code (3 Zeichen), z. B. `"URL"` für Urlaub.
startDate	string	Erster Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Letzter Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst, berechnet gemäß dem Arbeitszeitplan des Mitarbeiters.
status	string	Aktueller Status des Antrags. Einer von `pending` (wartet auf Genehmigung), `approved` oder `rejected`. Mögliche Werte: pending approved rejected
halfDay	string	Halbtags-Indikator. `"morning"` oder `"afternoon"` für Halbtagsanträge; `null` für ganztägige Abwesenheiten. Mögliche Werte: morning afternoon
substitutePending	boolean	Ob die Bestätigung des Vertreters noch aussteht. `null`, wenn kein Vertreter gesetzt wurde.
medicalCertificateProvided	boolean	Ob ein Attest für diese Abwesenheit hochgeladen wurde. Nur vorhanden bei Abwesenheitstypen, die ein Attest erfordern; sonst `null`.
employeeName	string	Anzeigename des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.
employeeId	string	Interne ID des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X POST "https://app.timebutler.com/api/v2/absence-requests" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"absenceTypeId":"URL","startDate":"2025-08-01","endDate":"2025-08-05","halfDay":"morning","comments":"Holiday trip","substituteEmployeeId":"42"}'

Bestehenden Abwesenheitsantrag aktualisieren

Aktualisiert einen Antrag, der sich noch im Zustand `pending` oder `edit` befindet. Nur die im Request-Body übermittelten Felder werden geändert; `null`-Felder bleiben unverändert. Nicht-Administratoren können nur ihre eigenen Anträge aktualisieren. Bereits genehmigte oder abgelehnte Anträge können nicht mehr aktualisiert werden und liefern `409 Conflict`.

Name	Typ	Description
iderforderlich	integer(int32)	Interne ID des zu aktualisierenden Abwesenheitsantrags. Entspricht dem `id`-Feld aus `GET /my` oder `GET /team`.

Zu aktualisierende Felder. Ein Feld weglassen (oder `null` senden), um den bestehenden Wert zu behalten.

Name	Typ	Description
absenceTypeId	string	Neuer Abwesenheitstyp-Code (3 Zeichen). `null` senden, um den bestehenden Typ zu behalten.
startDate	string	Neues Startdatum im ISO-8601-Format (`YYYY-MM-DD`). `null` senden, um den bestehenden Wert zu behalten.
endDate	string	Neues Enddatum im ISO-8601-Format (`YYYY-MM-DD`). Muss gleich oder nach `startDate` liegen. `null` senden, um den bestehenden Wert zu behalten.
halfDay	string	Neue Halbtags-Einstellung. `"morning"` oder `"afternoon"` um auf einen Halbtag zu wechseln; leerer String `""` um den Halbtag zu entfernen und auf ganztägig zu stellen; `null` um den bestehenden Wert zu behalten. Mögliche Werte: morning afternoon
comments	string	Neuer Freitextkommentar. `null` senden, um den bestehenden Kommentar zu behalten; leeren String senden, um ihn zu löschen.
substituteEmployeeId	string	Neue Vertreter-Mitarbeiter-ID. `null` senden, um den bestehenden Vertreter zu behalten; `"0"` oder einen leeren String senden, um den Vertreter zu entfernen.

Name	Typ	Description
id	string	Interne ID des Abwesenheitsantrags.
type	string	Abwesenheitstyp-Code (3 Zeichen), z. B. `"URL"` für Urlaub.
startDate	string	Erster Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Letzter Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst, berechnet gemäß dem Arbeitszeitplan des Mitarbeiters.
status	string	Aktueller Status des Antrags. Einer von `pending` (wartet auf Genehmigung), `approved` oder `rejected`. Mögliche Werte: pending approved rejected
halfDay	string	Halbtags-Indikator. `"morning"` oder `"afternoon"` für Halbtagsanträge; `null` für ganztägige Abwesenheiten. Mögliche Werte: morning afternoon
substitutePending	boolean	Ob die Bestätigung des Vertreters noch aussteht. `null`, wenn kein Vertreter gesetzt wurde.
medicalCertificateProvided	boolean	Ob ein Attest für diese Abwesenheit hochgeladen wurde. Nur vorhanden bei Abwesenheitstypen, die ein Attest erfordern; sonst `null`.
employeeName	string	Anzeigename des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.
employeeId	string	Interne ID des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X PUT "https://app.timebutler.com/api/v2/absence-requests/{id}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"absenceTypeId":"URL","startDate":"2025-08-01","endDate":"2025-08-05","halfDay":"morning","comments":"Rescheduled trip","substituteEmployeeId":"42"}'

Abwesenheitsantrag löschen oder Stornierungsanfrage senden

Das Verhalten hängt vom aktuellen Zustand des Antrags und den Rechten des Aufrufers ab: Darf der Aufrufer den Antrag direkt löschen, wird er entfernt und das Feld `result` der Antwort ist `"deleted"`. Andernfalls wird ein Stornierungsantrag erzeugt, den die Manager des Mitarbeiters dann genehmigen müssen, und die Antwort `result` ist `"cancellation_requested"`. Die Unternehmenskonfiguration kann eine Begründung erforderlich machen, wenn nur eine Stornierung möglich ist.

Name	Typ	Description
iderforderlich	integer(int32)	Interne ID des zu löschenden oder zu stornierenden Abwesenheitsantrags.

Optionaler Body mit einem freien `reason`-Text. Erforderlich für Stornierungsanfragen, wenn die Unternehmenskonfiguration eine Begründung verlangt.

Name	Typ	Description
reason	string	Optionaler Freitextgrund für die Stornierung. Erforderlich, wenn die Unternehmenskonfiguration einen Grund für Stornierungsanträge vorschreibt.

Name	Typ	Description
id	string	Interne ID des betroffenen Eintrags.
result	string	Ergebnis der Operation. `"deleted"`, wenn der Eintrag direkt gelöscht wurde; `"cancellation_requested"`, wenn stattdessen ein Stornierungsantrag erstellt wurde; `"deletion_requested"`, wenn ein Löschantrag erstellt wurde (für Zeiteinträge, die genehmigt werden müssen). Mögliche Werte: deleted cancellation_requested deletion_requested

{
  "id" : "12345",
  "result" : "deleted"
}

curl -X DELETE "https://app.timebutler.com/api/v2/absence-requests/{id}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Plans changed"}'

Eigene Abwesenheitsanträge des Aufrufers auflisten

Liefert jeden Abwesenheits- und Urlaubsantrag des Aufrufers, in jedem Zustand (pending, approved, rejected, done). Anträge, die der Aufrufer für seine unterstellten Mitarbeiter verwaltet, sind nicht enthalten — dafür siehe `/team`.

[ {
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-requests/my" \
  -H "Authorization: Bearer <token>"

Offene Antragszahlen für das Team des Aufrufers

Liefert zwei Zähler für die direkt unterstellten Mitarbeiter des Aufrufers: offene Abwesenheitsanträge, die auf seine Genehmigung warten, und offene Stornierungsanträge. Wird verwendet, um Benachrichtigungs-Badges im Manager-Dashboard anzuzeigen. Liefert Nullen, wenn der Aufrufer keine direkt unterstellten Mitarbeiter hat.

Name	Typ	Description
numberOfAbsenceRequests	integer(int32)	Anzahl der Abwesenheitsanträge im Team des Aufrufers, die auf die Genehmigung des Aufrufers warten.
numberOfAbsenceRequestCancellations	integer(int32)	Anzahl der Stornierungsanträge im Team des Aufrufers, die auf eine Genehmigung warten.

{
  "numberOfAbsenceRequests" : 3,
  "numberOfAbsenceRequestCancellations" : 1
}

curl -X GET "https://app.timebutler.com/api/v2/absence-requests/pending-count" \
  -H "Authorization: Bearer <token>"

Abwesenheitsanträge der unterstellten Mitarbeiter auflisten

Liefert jeden Abwesenheitsantrag von Mitarbeitern, die der Aufrufer verwaltet (Administratoren sehen alle Unternehmensnutzer), über alle Zustände hinweg. Jeder Eintrag enthält den Anzeigenamen und die ID des Mitarbeiters, damit das Ergebnis als Teamkalender oder Prüfliste dargestellt werden kann. Leeres Array, wenn der Aufrufer keine unterstellten Mitarbeiter hat.

[ {
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-requests/team" \
  -H "Authorization: Bearer <token>"

Offenen Abwesenheitsantrag ablehnen

Markiert einen offenen Abwesenheitsantrag als abgelehnt. Ein optionaler Ablehnungsgrund kann im Body übergeben werden — er wird gespeichert und dem antragstellenden Mitarbeiter angezeigt. Der Aufrufer muss Administrator oder direkter Vorgesetzter des Antragstellers sein.

Name	Typ	Description
iderforderlich	integer(int32)	Interne ID des abzulehnenden Abwesenheitsantrags.

Optionaler Body mit einem `reason`-String, der dem Mitarbeiter angezeigt wird.

Name	Typ	Description
reason	string	Optionaler Freitextgrund für die Ablehnung. Wird am Antrag gespeichert und dem Mitarbeiter angezeigt.

Name	Typ	Description
id	string	Interne ID des Abwesenheitsantrags.
type	string	Abwesenheitstyp-Code (3 Zeichen), z. B. `"URL"` für Urlaub.
startDate	string	Erster Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Letzter Tag der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst, berechnet gemäß dem Arbeitszeitplan des Mitarbeiters.
status	string	Aktueller Status des Antrags. Einer von `pending` (wartet auf Genehmigung), `approved` oder `rejected`. Mögliche Werte: pending approved rejected
halfDay	string	Halbtags-Indikator. `"morning"` oder `"afternoon"` für Halbtagsanträge; `null` für ganztägige Abwesenheiten. Mögliche Werte: morning afternoon
substitutePending	boolean	Ob die Bestätigung des Vertreters noch aussteht. `null`, wenn kein Vertreter gesetzt wurde.
medicalCertificateProvided	boolean	Ob ein Attest für diese Abwesenheit hochgeladen wurde. Nur vorhanden bei Abwesenheitstypen, die ein Attest erfordern; sonst `null`.
employeeName	string	Anzeigename des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.
employeeId	string	Interne ID des Mitarbeiters, der den Antrag gestellt hat. Nur in Antworten von `GET /team` vorhanden; `null` in `GET /my`-Antworten.

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X POST "https://app.timebutler.com/api/v2/absence-requests/{id}/reject" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Insufficient staffing during that period"}'

Abwesenheitsarten auflisten

Gibt alle aktiven Abwesenheitsarten zurück, die der authentifizierte Benutzer einreichen darf.

[ {
  "id" : "URL",
  "name" : "Urlaub",
  "needsApproval" : true,
  "requiresMedicalCertificate" : false
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-types" \
  -H "Authorization: Bearer <token>"

Profil abrufen

Gibt Anzeigename, E-Mail-Adresse, Rolle (`USER`, `MANAGER`, `ADMIN`), Abteilung, Niederlassung und Avatar-URL des authentifizierten Benutzers zurück.

Name	Typ	Description
id	string	Interne ID des authentifizierten Benutzers.
name	string	Vollständiger Anzeigename des Benutzers.
email	string	E-Mail-Adresse des Benutzers.
role	string	Rolle des Benutzers im Unternehmen. Einer von `USER`, `MANAGER` oder `ADMIN`. Mögliche Werte: USER MANAGER ADMIN
department	string	Name der Abteilung, der der Benutzer angehört. `null`, wenn das Unternehmen keine Abteilungen verwendet.
branchOffice	string	Name der Niederlassung, der der Benutzer zugeordnet ist. `null`, wenn das Unternehmen keine Niederlassungen verwendet.
country	object	Land des Benutzers, wie in seinem Profil konfiguriert. Die Struktur hängt von der Unternehmenskonfiguration ab.
avatar	string	URL des Profilbilds des Benutzers. `null`, wenn kein Profilbild hochgeladen wurde.
isBusinessTripEnabled	boolean	Ob die Dienstreisefunktion für diesen Benutzer aktiviert ist. `null`, wenn die Funktion im Unternehmensplan nicht verfügbar ist.
isTimeTrackingEnabled	boolean	Ob die Zeiterfassung für das Unternehmen des Benutzers aktiv ist.

{
  "id" : "42",
  "name" : "Maria Müller",
  "email" : "maria.mueller@example.com",
  "role" : "MANAGER",
  "department" : "Engineering",
  "branchOffice" : "Berlin",
  "country" : { },
  "avatar" : "/images/avatar/42/abc123.jpg?v=5",
  "isBusinessTripEnabled" : true,
  "isTimeTrackingEnabled" : true
}

curl -X GET "https://app.timebutler.com/api/v2/user/profile" \
  -H "Authorization: Bearer <token>"

Kategorien auflisten

Gibt alle aktiven Kategorien sowie die Standardkategorie des Benutzers und die Information zurück, ob eine Kategorie beim Speichern eines Zeiteintrags erforderlich ist.

Name	Typ	Description
categories	CategoryDto[]	Liste der Kostenstellen/Kategorien, die für das Unternehmen des authentifizierten Benutzers verfügbar sind.
id	string	Interne ID der Kategorie, die beim Einreichen eines Zeiteintrags verwendet wird.
name	string	Lesbarer Name der Kategorie.
defaultCategoryId	string	ID der Kategorie, die beim Erstellen eines Zeiteintrags standardmäßig vorausgewählt ist. `null`, wenn kein Standard konfiguriert ist.
isCategoryMandatory	boolean	Ob der Mitarbeiter beim Erstellen eines Zeiteintrags eine Kategorie auswählen muss.

{
  "categories" : [ {
    "id" : "7",
    "name" : "Internal project"
  } ],
  "defaultCategoryId" : "7",
  "isCategoryMandatory" : false
}

curl -X GET "https://app.timebutler.com/api/v2/categories" \
  -H "Authorization: Bearer <token>"

Projekte auflisten

Gibt alle aktiven Projekte zurück. Die Favoriten des Benutzers erscheinen zuerst, gefolgt von allen weiteren aktiven Projekten. Enthält außerdem das Standardprojekt des Benutzers und die Information, ob ein Projekt Pflichtfeld ist.

Name	Typ	Description
projects	ProjectDto[]	Liste der Projekte, die für das Unternehmen des authentifizierten Benutzers verfügbar sind.
id	string	Interne ID des Projekts, die beim Einreichen eines Zeiteintrags verwendet wird.
name	string	Lesbarer Name des Projekts.
isFavorite	boolean	Ob dieses Projekt vom authentifizierten Benutzer als Favorit markiert wurde.
defaultProjectId	string	ID des Projekts, das beim Erstellen eines Zeiteintrags standardmäßig vorausgewählt ist. `null`, wenn kein Standard konfiguriert ist.
isProjectMandatory	boolean	Ob der Mitarbeiter beim Erstellen eines Zeiteintrags ein Projekt auswählen muss.

{
  "projects" : [ {
    "id" : "5",
    "name" : "Website Relaunch",
    "isFavorite" : true
  } ],
  "defaultProjectId" : "5",
  "isProjectMandatory" : true
}

curl -X GET "https://app.timebutler.com/api/v2/projects" \
  -H "Authorization: Bearer <token>"

Dienstgang beenden

Markiert das Ende eines aktiven Dienstgangs auf der aktuellen Stempeluhr. Gibt 409 zurück, wenn kein Dienstgang aktiv ist.

Name	Typ	Description
status	string	Aktueller Zustand der Zeiterfassung. Einer von `idle` (nicht aktiv), `running` (eingestempelt), `paused` oder `waiting` (gestartet, aber bis zum Ablauf eines Mindestintervalls gehalten). Mögliche Werte: idle running paused waiting
startTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Einstempelung begonnen hat. `null`, wenn `status` `idle` ist.
pauseTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Pause begonnen hat. `null`, wenn die Uhr nicht pausiert ist.
workTimeElapsedSeconds	integer(int32)	Gesamte bisher vergangene Arbeitszeit in der aktuellen Sitzung, in Sekunden (ohne Pausen).
breakElapsedSeconds	integer(int32)	Dauer der aktuell laufenden Pause, in Sekunden. `0`, wenn die Uhr nicht pausiert ist.
accumulatedBreakSeconds	integer(int32)	Gesamte aufgelaufene Pausenzeit in der aktuellen Sitzung, in Sekunden (einschließlich abgeschlossener Pausen).
waitSeconds	integer(int32)	Mindestanzahl verbleibender Sekunden, bevor der Mitarbeiter gemäß Unternehmensrichtlinie ausstempeln darf. `null`, wenn kein Minimum gilt.
isBusinessTripActive	boolean	Ob für diese Sitzung aktuell eine Dienstreise aktiv ist. `false`, wenn keine Dienstreise aktiv ist oder die Funktion nicht aktiviert ist.

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/business-trip-end" \
  -H "Authorization: Bearer <token>"

Dienstgang starten

Markiert den Beginn eines Dienstgangs auf der aktuell laufenden oder pausierten Stempeluhr. Gibt 400 zurück, wenn Dienstgänge für dieses Unternehmen nicht aktiviert sind; gibt 409 zurück, wenn die Stempeluhr nicht aktiv ist oder ein Dienstgang bereits läuft.

Name	Typ	Description
status	string	Aktueller Zustand der Zeiterfassung. Einer von `idle` (nicht aktiv), `running` (eingestempelt), `paused` oder `waiting` (gestartet, aber bis zum Ablauf eines Mindestintervalls gehalten). Mögliche Werte: idle running paused waiting
startTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Einstempelung begonnen hat. `null`, wenn `status` `idle` ist.
pauseTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Pause begonnen hat. `null`, wenn die Uhr nicht pausiert ist.
workTimeElapsedSeconds	integer(int32)	Gesamte bisher vergangene Arbeitszeit in der aktuellen Sitzung, in Sekunden (ohne Pausen).
breakElapsedSeconds	integer(int32)	Dauer der aktuell laufenden Pause, in Sekunden. `0`, wenn die Uhr nicht pausiert ist.
accumulatedBreakSeconds	integer(int32)	Gesamte aufgelaufene Pausenzeit in der aktuellen Sitzung, in Sekunden (einschließlich abgeschlossener Pausen).
waitSeconds	integer(int32)	Mindestanzahl verbleibender Sekunden, bevor der Mitarbeiter gemäß Unternehmensrichtlinie ausstempeln darf. `null`, wenn kein Minimum gilt.
isBusinessTripActive	boolean	Ob für diese Sitzung aktuell eine Dienstreise aktiv ist. `false`, wenn keine Dienstreise aktiv ist oder die Funktion nicht aktiviert ist.

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/business-trip-start" \
  -H "Authorization: Bearer <token>"

Stempeluhr abbrechen

Verwirft die aktuelle Stempeluhr-Sitzung ohne einen Zeiteintrag zu speichern. Gibt 409 zurück, wenn die Stempeluhr bereits `idle` ist.

Name	Typ	Description
status	string	Aktueller Zustand der Zeiterfassung. Einer von `idle` (nicht aktiv), `running` (eingestempelt), `paused` oder `waiting` (gestartet, aber bis zum Ablauf eines Mindestintervalls gehalten). Mögliche Werte: idle running paused waiting
startTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Einstempelung begonnen hat. `null`, wenn `status` `idle` ist.
pauseTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Pause begonnen hat. `null`, wenn die Uhr nicht pausiert ist.
workTimeElapsedSeconds	integer(int32)	Gesamte bisher vergangene Arbeitszeit in der aktuellen Sitzung, in Sekunden (ohne Pausen).
breakElapsedSeconds	integer(int32)	Dauer der aktuell laufenden Pause, in Sekunden. `0`, wenn die Uhr nicht pausiert ist.
accumulatedBreakSeconds	integer(int32)	Gesamte aufgelaufene Pausenzeit in der aktuellen Sitzung, in Sekunden (einschließlich abgeschlossener Pausen).
waitSeconds	integer(int32)	Mindestanzahl verbleibender Sekunden, bevor der Mitarbeiter gemäß Unternehmensrichtlinie ausstempeln darf. `null`, wenn kein Minimum gilt.
isBusinessTripActive	boolean	Ob für diese Sitzung aktuell eine Dienstreise aktiv ist. `false`, wenn keine Dienstreise aktiv ist oder die Funktion nicht aktiviert ist.

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/cancel" \
  -H "Authorization: Bearer <token>"

Stempeluhr-Status abrufen

Gibt den aktuellen Status der Stempeluhr zurück: `idle`, `running`, `paused` oder `waiting`. Enthält außerdem die verstrichene Zeit, die Pausenzeit und den Dienstgang-Status.

Name	Typ	Description
status	string	Aktueller Zustand der Zeiterfassung. Einer von `idle` (nicht aktiv), `running` (eingestempelt), `paused` oder `waiting` (gestartet, aber bis zum Ablauf eines Mindestintervalls gehalten). Mögliche Werte: idle running paused waiting
startTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Einstempelung begonnen hat. `null`, wenn `status` `idle` ist.
pauseTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Pause begonnen hat. `null`, wenn die Uhr nicht pausiert ist.
workTimeElapsedSeconds	integer(int32)	Gesamte bisher vergangene Arbeitszeit in der aktuellen Sitzung, in Sekunden (ohne Pausen).
breakElapsedSeconds	integer(int32)	Dauer der aktuell laufenden Pause, in Sekunden. `0`, wenn die Uhr nicht pausiert ist.
accumulatedBreakSeconds	integer(int32)	Gesamte aufgelaufene Pausenzeit in der aktuellen Sitzung, in Sekunden (einschließlich abgeschlossener Pausen).
waitSeconds	integer(int32)	Mindestanzahl verbleibender Sekunden, bevor der Mitarbeiter gemäß Unternehmensrichtlinie ausstempeln darf. `null`, wenn kein Minimum gilt.
isBusinessTripActive	boolean	Ob für diese Sitzung aktuell eine Dienstreise aktiv ist. `false`, wenn keine Dienstreise aktiv ist oder die Funktion nicht aktiviert ist.

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false
}

curl -X GET "https://app.timebutler.com/api/v2/time-clock/status" \
  -H "Authorization: Bearer <token>"

Stempeluhr pausieren

Pausiert eine laufende Stempeluhr. Gibt 409 zurück, wenn die Stempeluhr nicht im Status `running` ist.

Name	Typ	Description
status	string	Aktueller Zustand der Zeiterfassung. Einer von `idle` (nicht aktiv), `running` (eingestempelt), `paused` oder `waiting` (gestartet, aber bis zum Ablauf eines Mindestintervalls gehalten). Mögliche Werte: idle running paused waiting
startTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Einstempelung begonnen hat. `null`, wenn `status` `idle` ist.
pauseTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Pause begonnen hat. `null`, wenn die Uhr nicht pausiert ist.
workTimeElapsedSeconds	integer(int32)	Gesamte bisher vergangene Arbeitszeit in der aktuellen Sitzung, in Sekunden (ohne Pausen).
breakElapsedSeconds	integer(int32)	Dauer der aktuell laufenden Pause, in Sekunden. `0`, wenn die Uhr nicht pausiert ist.
accumulatedBreakSeconds	integer(int32)	Gesamte aufgelaufene Pausenzeit in der aktuellen Sitzung, in Sekunden (einschließlich abgeschlossener Pausen).
waitSeconds	integer(int32)	Mindestanzahl verbleibender Sekunden, bevor der Mitarbeiter gemäß Unternehmensrichtlinie ausstempeln darf. `null`, wenn kein Minimum gilt.
isBusinessTripActive	boolean	Ob für diese Sitzung aktuell eine Dienstreise aktiv ist. `false`, wenn keine Dienstreise aktiv ist oder die Funktion nicht aktiviert ist.

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/pause" \
  -H "Authorization: Bearer <token>"

Stempeluhr fortsetzen

Setzt eine pausierte Stempeluhr fort. Gibt 409 zurück, wenn die Stempeluhr nicht im Status `paused` ist.

Name	Typ	Description
status	string	Aktueller Zustand der Zeiterfassung. Einer von `idle` (nicht aktiv), `running` (eingestempelt), `paused` oder `waiting` (gestartet, aber bis zum Ablauf eines Mindestintervalls gehalten). Mögliche Werte: idle running paused waiting
startTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Einstempelung begonnen hat. `null`, wenn `status` `idle` ist.
pauseTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Pause begonnen hat. `null`, wenn die Uhr nicht pausiert ist.
workTimeElapsedSeconds	integer(int32)	Gesamte bisher vergangene Arbeitszeit in der aktuellen Sitzung, in Sekunden (ohne Pausen).
breakElapsedSeconds	integer(int32)	Dauer der aktuell laufenden Pause, in Sekunden. `0`, wenn die Uhr nicht pausiert ist.
accumulatedBreakSeconds	integer(int32)	Gesamte aufgelaufene Pausenzeit in der aktuellen Sitzung, in Sekunden (einschließlich abgeschlossener Pausen).
waitSeconds	integer(int32)	Mindestanzahl verbleibender Sekunden, bevor der Mitarbeiter gemäß Unternehmensrichtlinie ausstempeln darf. `null`, wenn kein Minimum gilt.
isBusinessTripActive	boolean	Ob für diese Sitzung aktuell eine Dienstreise aktiv ist. `false`, wenn keine Dienstreise aktiv ist oder die Funktion nicht aktiviert ist.

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/resume" \
  -H "Authorization: Bearer <token>"

Stempeluhr starten

Startet die Stempeluhr für den authentifizierten Benutzer. Gibt 409 zurück, wenn die Stempeluhr bereits läuft. Die Uhr kann den Status `waiting` annehmen, wenn ein Mindest-Startintervall konfiguriert ist.

Name	Typ	Description
status	string	Aktueller Zustand der Zeiterfassung. Einer von `idle` (nicht aktiv), `running` (eingestempelt), `paused` oder `waiting` (gestartet, aber bis zum Ablauf eines Mindestintervalls gehalten). Mögliche Werte: idle running paused waiting
startTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Einstempelung begonnen hat. `null`, wenn `status` `idle` ist.
pauseTimestamp	integer(int64)	Unix-Zeitstempel in Millisekunden, wann die aktuelle Pause begonnen hat. `null`, wenn die Uhr nicht pausiert ist.
workTimeElapsedSeconds	integer(int32)	Gesamte bisher vergangene Arbeitszeit in der aktuellen Sitzung, in Sekunden (ohne Pausen).
breakElapsedSeconds	integer(int32)	Dauer der aktuell laufenden Pause, in Sekunden. `0`, wenn die Uhr nicht pausiert ist.
accumulatedBreakSeconds	integer(int32)	Gesamte aufgelaufene Pausenzeit in der aktuellen Sitzung, in Sekunden (einschließlich abgeschlossener Pausen).
waitSeconds	integer(int32)	Mindestanzahl verbleibender Sekunden, bevor der Mitarbeiter gemäß Unternehmensrichtlinie ausstempeln darf. `null`, wenn kein Minimum gilt.
isBusinessTripActive	boolean	Ob für diese Sitzung aktuell eine Dienstreise aktiv ist. `false`, wenn keine Dienstreise aktiv ist oder die Funktion nicht aktiviert ist.

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/start" \
  -H "Authorization: Bearer <token>"

Stempeluhr stoppen und speichern

Stoppt die laufende oder pausierte Stempeluhr und speichert den resultierenden Zeiteintrag. Optional können eine Projekt-ID und Anmerkungen angegeben werden. Befindet sich die Uhr im Status `waiting`, wird sie verworfen und 204 zurückgegeben. Gibt 409 zurück, wenn die Gesamtdauer zu kurz ist (< 1 Minute) oder ein doppelter Eintrag erkannt wird.

Optionale Projekt-ID, Kategorie-ID und Anmerkungen für den gespeicherten Eintrag.

Name	Typ	Description
projectId	integer(int32)	ID des Projekts, dem die abgeschlossene Sitzung zugeordnet werden soll. `0` senden, wenn keine Projektzuordnung benötigt wird.
categoryId	integer(int32)	ID der Kategorie, der die abgeschlossene Sitzung zugeordnet werden soll. `0` senden, wenn keine Kategoriezuordnung benötigt wird.
remarks	string	Optionaler Freitextkommentar für den abgeschlossenen Zeiteintrag.

Name	Typ	Description
id	string	Interne ID des Zeiteintrags, der beim Ausstempeln erstellt wurde.
workedMinutes	integer(int32)	Erfasste Nettoarbeitszeit der Sitzung, in Minuten (Gesamtdauer minus Pausen).
breakMinutes	integer(int32)	Erfasste Gesamtpausenzeit der Sitzung, in Minuten.

{
  "id" : "98765",
  "workedMinutes" : 480,
  "breakMinutes" : 30
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/stop" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"projectId":5,"categoryId":7,"remarks":"Code review"}'

Stornierungsantrag genehmigen

Genehmigt den ausstehenden Stornierungsantrag für die angegebene Abwesenheit. Die Abwesenheit wird gelöscht und Benachrichtigungs-E-Mails werden versendet. Erfordert die Rolle `MANAGER` oder `ADMIN`.

Name	Typ	Description
iderforderlich	integer(int32)	ID der Abwesenheit.

Name	Typ	Description
id	string	Interne ID des zu stornierenden Abwesenheitsantrags.
employeeId	string	Interne ID des Mitarbeiters, der den ursprünglichen Abwesenheitsantrag gestellt hat.
employeeName	string	Anzeigename des Mitarbeiters, der den ursprünglichen Abwesenheitsantrag gestellt hat.
absenceType	string	Abwesenheitstyp-Code (3 Zeichen) des zu stornierenden Antrags.
startDate	string	Startdatum der zu stornierenden Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Enddatum der zu stornierenden Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst.
status	string	Aktueller Status des Stornierungsantrags. Einer von `pending` (wartet auf Genehmigung) oder `approved`. Mögliche Werte: pending approved
cancelComments	string	Optionaler Freitextgrund, den der Mitarbeiter beim Stellen des Stornierungsantrags angegeben hat.

{
  "id" : "12345",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "cancelComments" : "Plans changed"
}

curl -X POST "https://app.timebutler.com/api/v2/cancellation-requests/{id}/approve" \
  -H "Authorization: Bearer <token>"

Offene Stornierungsanträge auflisten

Gibt alle offenen Stornierungsanträge zurück, die für den authentifizierten Vorgesetzten oder Administrator sichtbar sind. Erfordert die Rolle `MANAGER` oder `ADMIN`.

[ {
  "id" : "12345",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "cancelComments" : "Plans changed"
} ]

curl -X GET "https://app.timebutler.com/api/v2/cancellation-requests" \
  -H "Authorization: Bearer <token>"

Anzahl offener Stornierungsanträge abrufen

Gibt die Anzahl der Stornierungsanträge zurück, die auf eine Entscheidung eines Vorgesetzten oder Administrators warten. Erfordert die Rolle `MANAGER` oder `ADMIN`.

Name	Typ	Description
numberOfCancellationRequests	integer(int32)	Anzahl der Stornierungsanträge im Team des Aufrufers, die auf eine Genehmigung warten.

{
  "numberOfCancellationRequests" : 2
}

curl -X GET "https://app.timebutler.com/api/v2/cancellation-requests/pending-count" \
  -H "Authorization: Bearer <token>"

Stornierungsantrag ablehnen

Lehnt den ausstehenden Stornierungsantrag ab. Die Abwesenheit bleibt bestehen; der Mitarbeiter wird per E-Mail benachrichtigt. Erfordert die Rolle `MANAGER` oder `ADMIN`.

Name	Typ	Description
iderforderlich	integer(int32)	ID der Abwesenheit.

Name	Typ	Description
id	string	Interne ID des zu stornierenden Abwesenheitsantrags.
employeeId	string	Interne ID des Mitarbeiters, der den ursprünglichen Abwesenheitsantrag gestellt hat.
employeeName	string	Anzeigename des Mitarbeiters, der den ursprünglichen Abwesenheitsantrag gestellt hat.
absenceType	string	Abwesenheitstyp-Code (3 Zeichen) des zu stornierenden Antrags.
startDate	string	Startdatum der zu stornierenden Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Enddatum der zu stornierenden Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst.
status	string	Aktueller Status des Stornierungsantrags. Einer von `pending` (wartet auf Genehmigung) oder `approved`. Mögliche Werte: pending approved
cancelComments	string	Optionaler Freitextgrund, den der Mitarbeiter beim Stellen des Stornierungsantrags angegeben hat.

{
  "id" : "12345",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "cancelComments" : "Plans changed"
}

curl -X POST "https://app.timebutler.com/api/v2/cancellation-requests/{id}/reject" \
  -H "Authorization: Bearer <token>"

Vertretungsanfrage annehmen

Nimmt die Vertretungsanfrage für die angegebene Abwesenheit an. Nur die vorgesehene Vertretung darf diesen Endpunkt aufrufen.

Name	Typ	Description
iderforderlich	integer(int32)	ID der Abwesenheit.

Name	Typ	Description
id	string	Interne ID des Abwesenheitsantrags, für den die Vertretung angefragt wurde.
employeeId	string	Interne ID des abwesenden Mitarbeiters, der eine Vertretung benötigt.
employeeName	string	Anzeigename des abwesenden Mitarbeiters.
absenceType	string	Abwesenheitstyp-Code (3 Zeichen) der Abwesenheit, für die diese Vertretung angefragt wurde.
startDate	string	Startdatum der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Enddatum der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst.
status	string	Aktueller Status der Vertretungsbestätigung. Einer von `pending` (wartet auf Bestätigung des Vertreters) oder `confirmed`. Mögliche Werte: pending confirmed

{
  "id" : "12345",
  "employeeId" : "7",
  "employeeName" : "Anna Bauer",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/substitute-requests/{id}/accept" \
  -H "Authorization: Bearer <token>"

Anzahl offener Vertretungsanfragen abrufen

Gibt die Anzahl der Vertretungsanfragen zurück, die noch auf die Antwort des authentifizierten Benutzers warten.

Name	Typ	Description
numberOfSubstituteRequests	integer(int32)	Anzahl der Vertretungsanfragen, die auf die Bestätigung des Aufrufers warten.

{
  "numberOfSubstituteRequests" : 1
}

curl -X GET "https://app.timebutler.com/api/v2/substitute-requests/pending-count" \
  -H "Authorization: Bearer <token>"

Vertretungsanfragen auflisten

Gibt alle Vertretungsanfragen zurück, die an den authentifizierten Benutzer gerichtet sind, unabhängig von deren Status (ausstehend, angenommen, abgelehnt).

[ {
  "id" : "12345",
  "employeeId" : "7",
  "employeeName" : "Anna Bauer",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending"
} ]

curl -X GET "https://app.timebutler.com/api/v2/substitute-requests" \
  -H "Authorization: Bearer <token>"

Vertretungsanfrage ablehnen

Lehnt die Vertretungsanfrage für die angegebene Abwesenheit ab. Nur die vorgesehene Vertretung darf diesen Endpunkt aufrufen.

Name	Typ	Description
iderforderlich	integer(int32)	ID der Abwesenheit.

Name	Typ	Description
id	string	Interne ID des Abwesenheitsantrags, für den die Vertretung angefragt wurde.
employeeId	string	Interne ID des abwesenden Mitarbeiters, der eine Vertretung benötigt.
employeeName	string	Anzeigename des abwesenden Mitarbeiters.
absenceType	string	Abwesenheitstyp-Code (3 Zeichen) der Abwesenheit, für die diese Vertretung angefragt wurde.
startDate	string	Startdatum der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
endDate	string	Enddatum der Abwesenheit im ISO-8601-Format (`YYYY-MM-DD`).
days	number(double)	Anzahl der Werktage, die die Abwesenheit umfasst.
status	string	Aktueller Status der Vertretungsbestätigung. Einer von `pending` (wartet auf Bestätigung des Vertreters) oder `confirmed`. Mögliche Werte: pending confirmed

{
  "id" : "12345",
  "employeeId" : "7",
  "employeeName" : "Anna Bauer",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/substitute-requests/{id}/reject" \
  -H "Authorization: Bearer <token>"

Vertretungsmitarbeiter auflisten

Gibt alle aktiven Mitarbeiter des Unternehmens zurück, die als Vertretung für den authentifizierten Benutzer fungieren können. Der authentifizierte Benutzer selbst ist nicht in der Liste enthalten.

[ {
  "id" : "42",
  "name" : "Thomas Schmidt",
  "department" : "Engineering"
} ]

curl -X GET "https://app.timebutler.com/api/v2/substitute-employees" \
  -H "Authorization: Bearer <token>"

Zeiteintrag löschen

Löscht den angegebenen Zeiteintrag. Wenn die Zeiterfassungseinstellungen des Unternehmens eine Genehmigung durch den Vorgesetzten für Löschungen erfordern, wird stattdessen ein Löschantrag gestellt. Das Antwortfeld `result` ist entweder `deleted` oder `deletion_requested`.

Name	Typ	Description
iderforderlich	integer(int32)	ID des Zeiteintrags.

Name	Typ	Description
id	string	Interne ID des betroffenen Eintrags.
result	string	Ergebnis der Operation. `"deleted"`, wenn der Eintrag direkt gelöscht wurde; `"cancellation_requested"`, wenn stattdessen ein Stornierungsantrag erstellt wurde; `"deletion_requested"`, wenn ein Löschantrag erstellt wurde (für Zeiteinträge, die genehmigt werden müssen). Mögliche Werte: deleted cancellation_requested deletion_requested

{
  "id" : "12345",
  "result" : "deleted"
}

curl -X DELETE "https://app.timebutler.com/api/v2/time-entries/{id}" \
  -H "Authorization: Bearer <token>"

Anzahl ausstehender Zeiteinträge abrufen

Gibt die Anzahl der Zeiteinträge im Team des Vorgesetzten zurück, die auf Genehmigung warten. Erfordert die Rolle `MANAGER` oder `ADMIN`.

Name	Typ	Description
numberOfTimeEntries	integer(int32)	Anzahl der Zeiteinträge im Team des Aufrufers, die auf eine Genehmigung warten.

{
  "numberOfTimeEntries" : 5
}

curl -X GET "https://app.timebutler.com/api/v2/time-entries/pending-count" \
  -H "Authorization: Bearer <token>"

Abgeschlossenen Zeiteintrag einreichen

Erstellt einen Zeiteintrag aus expliziten Start- und End-Unix-Zeitstempeln (Millisekunden). Start und Ende müssen am selben Kalendertag liegen. Wenn das Unternehmen eine Genehmigung durch den Vorgesetzten für neue Einträge erfordert, wird der Eintrag mit dem Status `pending` erstellt; andernfalls ist er sofort `done`.

Zeiteintrag mit Start-/Endzeitstempeln sowie optionalem Projekt und Anmerkungen.

Name	Typ	Description
startTimestamperforderlich	integer(int64)	Beginn des Arbeitszeitraums als Unix-Zeitstempel in Millisekunden.
endTimestamperforderlich	integer(int64)	Ende des Arbeitszeitraums als Unix-Zeitstempel in Millisekunden.
pauseSeconds	integer(int32)	Gesamte Pausendauer innerhalb des Arbeitszeitraums, in Sekunden.
projectId	integer(int32)	ID des Projekts, dem dieser Eintrag zugeordnet werden soll. `0` senden, wenn keine Projektzuordnung benötigt wird.
remarks	string	Optionaler Freitextkommentar für diesen Zeiteintrag.

Name	Typ	Description
id	string	Interne ID des erstellten Zeiteintrags.
workedMinutes	integer(int32)	Erfasste Nettoarbeitszeit für diesen Eintrag, in Minuten (Gesamtdauer minus Pausen).
breakMinutes	integer(int32)	Erfasste Gesamtpausenzeit für diesen Eintrag, in Minuten.

{
  "id" : "98765",
  "workedMinutes" : 480,
  "breakMinutes" : 30
}

curl -X POST "https://app.timebutler.com/api/v2/time-tracking/clock-entry" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"startTimestamp":1753700400000,"endTimestamp":1753729200000,"pauseSeconds":1800,"projectId":5,"remarks":"Sprint planning"}'

Abwesenheitszusammenfassung abrufen

Gibt die verbleibenden und die Gesamtanzahl der Urlaubstage des authentifizierten Benutzers für das laufende Jahr sowie die Anzahl der genommenen Krankheitstage zurück.

Name	Typ	Description
vacationDaysRemaining	number(double)	Anzahl der Urlaubstage, die dem Mitarbeiter im laufenden Jahr noch zur Verfügung stehen, nach Berücksichtigung genehmigter und ausstehender Anträge.
vacationDaysTotal	number(double)	Gesamter Urlaubsanspruch des Mitarbeiters für das laufende Jahr.
illnessDaysTaken	number(double)	Anzahl der in diesem Jahr genommenen Krankheitstage.

{
  "vacationDaysRemaining" : 12.5,
  "vacationDaysTotal" : 30.0,
  "illnessDaysTaken" : 3.0
}

curl -X GET "https://app.timebutler.com/api/v2/time-tracking/time-off-summary" \
  -H "Authorization: Bearer <token>"

Heutige Arbeitszusammenfassung abrufen

Gibt die Sollarbeitszeit, die geleisteten Minuten, die verbleibenden Minuten, den Fertigstellungsgrad und die Pausenminuten des authentifizierten Benutzers für den heutigen Tag zurück.

Name	Typ	Description
commitmentMinutes	integer(int32)	Gesamte Arbeitszeit, die der Mitarbeiter im abgefragten Zeitraum vertraglich leisten muss, in Minuten.
workedMinutes	integer(int32)	Gesamte Arbeitszeit, die der Mitarbeiter im abgefragten Zeitraum tatsächlich geleistet hat, in Minuten.
remainingMinutes	integer(int32)	Verbleibende Arbeitszeit, die im abgefragten Zeitraum noch geleistet werden muss, in Minuten. Negative Werte bedeuten Überstunden.
percentDone	integer(int32)	Prozentsatz der vertraglichen Arbeitszeit, der bisher geleistet wurde, auf die nächste ganze Zahl gerundet.
breakMinutes	integer(int32)	Gesamte im abgefragten Zeitraum erfasste Pausenzeit, in Minuten.

{
  "commitmentMinutes" : 2400,
  "workedMinutes" : 2280,
  "remainingMinutes" : 120,
  "percentDone" : 95,
  "breakMinutes" : 300
}

curl -X GET "https://app.timebutler.com/api/v2/time-tracking/work-summary" \
  -H "Authorization: Bearer <token>"

Zeiterfassungsantrag genehmigen

Genehmigt den ausstehenden Änderungs- oder Löschantrag für den angegebenen Zeiteintrag. Bei Löschanträgen wird der Eintrag entfernt; bei Änderungsanträgen wird der Eintrag auf die vorgeschlagenen Werte aktualisiert. Erfordert die Rolle `MANAGER` oder `ADMIN`.

Name	Typ	Description
iderforderlich	integer(int32)	ID des Zeiteintrags.

Name	Typ	Description
id	string	Interne ID des Zeiteintrags.
employeeId	string	Interne ID des Mitarbeiters, der den Zeiteintrag eingereicht hat. Nur in Team-/Manageransichten vorhanden.
employeeName	string	Anzeigename des Mitarbeiters, der den Zeiteintrag eingereicht hat. Nur in Team-/Manageransichten vorhanden.
date	string	Datum des Zeiteintrags im ISO-8601-Format (`YYYY-MM-DD`).
startTime	string	Einstempelzeit im Format `HH:mm`.
endTime	string	Ausstempelzeit im Format `HH:mm`.
workedMinutes	integer(int32)	Nettoarbeitszeit für diesen Eintrag, in Minuten (Gesamtdauer minus Pausen).
breakMinutes	integer(int32)	Gesamte Pausenzeit für diesen Eintrag, in Minuten.
project	string	Name des Projekts, das diesem Eintrag zugeordnet ist. `null`, wenn kein Projekt zugeordnet wurde.
category	string	Name der Kategorie, die diesem Eintrag zugeordnet ist. `null`, wenn keine Kategorie zugeordnet wurde.
remarks	string	Freitextkommentar, der diesem Eintrag beigefügt ist. `null`, wenn kein Kommentar eingegeben wurde.
requestType	string	Typ der Anfrage, die diesen Eintrag erzeugt hat. Einer von `manual` (manuell eingegeben) oder `clock` (durch Ausstempeln erstellt). Mögliche Werte: manual clock
status	string	Genehmigungsstatus dieses Zeiteintrags. Einer von `pending` (wartet auf Genehmigung) oder `approved`. Mögliche Werte: pending approved

{
  "id" : "98765",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "date" : "2025-07-28",
  "startTime" : "08:00",
  "endTime" : "17:00",
  "workedMinutes" : 480,
  "breakMinutes" : 60,
  "project" : "Website Relaunch",
  "category" : "Internal project",
  "remarks" : "Sprint planning",
  "requestType" : "manual",
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/time-entry-requests/{id}/approve" \
  -H "Authorization: Bearer <token>"

Ausstehende Zeiterfassungsanträge auflisten

Gibt alle ausstehenden Zeiterfassungsanträge im Team des Vorgesetzten zurück, die auf Genehmigung warten. Erfordert die Rolle `MANAGER` oder `ADMIN`. Gibt eine leere Liste zurück, wenn die Zeiterfassung nicht aktiv ist oder der Aufrufer ein Vorgesetzter in einem Unternehmen mit ausschließlicher Admin-Genehmigung ist.

[ {
  "id" : "98765",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "date" : "2025-07-28",
  "startTime" : "08:00",
  "endTime" : "17:00",
  "workedMinutes" : 480,
  "breakMinutes" : 60,
  "project" : "Website Relaunch",
  "category" : "Internal project",
  "remarks" : "Sprint planning",
  "requestType" : "manual",
  "status" : "pending"
} ]

curl -X GET "https://app.timebutler.com/api/v2/time-entry-requests" \
  -H "Authorization: Bearer <token>"

Zeiterfassungsantrag ablehnen

Lehnt den ausstehenden Änderungs- oder Löschantrag für den angegebenen Zeiteintrag ab. Ein optionaler Ablehnungsgrund kann im Anfragetext angegeben werden. Der Mitarbeiter wird per E-Mail benachrichtigt. Erfordert die Rolle `MANAGER` oder `ADMIN`.

Name	Typ	Description
iderforderlich	integer(int32)	ID des Zeiteintrags.

Optionaler Ablehnungsgrund.

Name	Typ	Description
reason	string	Optionaler Freitextgrund für die Ablehnung. Wird am Antrag gespeichert und dem Mitarbeiter angezeigt.

Name	Typ	Description
id	string	Interne ID des Zeiteintrags.
employeeId	string	Interne ID des Mitarbeiters, der den Zeiteintrag eingereicht hat. Nur in Team-/Manageransichten vorhanden.
employeeName	string	Anzeigename des Mitarbeiters, der den Zeiteintrag eingereicht hat. Nur in Team-/Manageransichten vorhanden.
date	string	Datum des Zeiteintrags im ISO-8601-Format (`YYYY-MM-DD`).
startTime	string	Einstempelzeit im Format `HH:mm`.
endTime	string	Ausstempelzeit im Format `HH:mm`.
workedMinutes	integer(int32)	Nettoarbeitszeit für diesen Eintrag, in Minuten (Gesamtdauer minus Pausen).
breakMinutes	integer(int32)	Gesamte Pausenzeit für diesen Eintrag, in Minuten.
project	string	Name des Projekts, das diesem Eintrag zugeordnet ist. `null`, wenn kein Projekt zugeordnet wurde.
category	string	Name der Kategorie, die diesem Eintrag zugeordnet ist. `null`, wenn keine Kategorie zugeordnet wurde.
remarks	string	Freitextkommentar, der diesem Eintrag beigefügt ist. `null`, wenn kein Kommentar eingegeben wurde.
requestType	string	Typ der Anfrage, die diesen Eintrag erzeugt hat. Einer von `manual` (manuell eingegeben) oder `clock` (durch Ausstempeln erstellt). Mögliche Werte: manual clock
status	string	Genehmigungsstatus dieses Zeiteintrags. Einer von `pending` (wartet auf Genehmigung) oder `approved`. Mögliche Werte: pending approved

{
  "id" : "98765",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "date" : "2025-07-28",
  "startTime" : "08:00",
  "endTime" : "17:00",
  "workedMinutes" : 480,
  "breakMinutes" : 60,
  "project" : "Website Relaunch",
  "category" : "Internal project",
  "remarks" : "Sprint planning",
  "requestType" : "manual",
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/time-entry-requests/{id}/reject" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Insufficient staffing during that period"}'