Abwesenheiten abrufen

Beta Die REST-API ist in der Beta. Endpunkte und Felder können sich bis zur Version 1.0.0 noch ändern.

GET/api/v1/absencesScopeabsences:read

GET /api/v1/absences liefert die Abwesenheiten der Mitarbeiter deines Standorts, zum Beispiel Urlaub, Krankheit oder Weiterbildung. Benötigter Scope: absences:read (Berechtigung Abwesenheiten). Die Einträge sind nach start, dann id sortiert.

Mit from und to erhältst du alle Abwesenheiten, die den Zeitraum berühren – also auch solche, die vorher beginnen oder danach enden. Ohne from und to liefert die API alle Abwesenheiten.

Parameter

Name	Pflicht	Typ	Beschreibung
from	nein	Datum YYYY-MM-DD	Erster Tag des Zeitraums (inklusive, Europe/Berlin)
to	nein	Datum YYYY-MM-DD	Letzter Tag des Zeitraums (inklusive, Europe/Berlin). Darf nicht vor from liegen
employeeId	nein	ID	Nur Abwesenheiten dieses Mitarbeiters
type	nein	Art, siehe unten	Nur Abwesenheiten dieser Art, zum Beispiel Vacation
limit	nein	Ganzzahl 1–500	Einträge pro Seite. Standard: 100
cursor	nein	String	Wert von nextCursor aus der vorherigen Antwort

Antwortfelder

Feld	Typ	Beschreibung
id	String	ID der Abwesenheit
employeeId	String	ID des Mitarbeiters
type	String	Art der Abwesenheit, siehe unten
start	Zeitpunkt	Beginn der Abwesenheit (ISO 8601, UTC)
end	Zeitpunkt	Ende der Abwesenheit (ISO 8601, UTC)
paid	Boolean oder null	Ob die Abwesenheit als bezahlt eingetragen ist; null, wenn keine Angabe vorliegt
name	String oder null	Freitext-Bezeichnung, falls vergeben. Bei Elternzeit immer null
status	String	Antragsstatus, siehe unten
halfDays	Liste von Datumsangaben	Tage (YYYY-MM-DD, Europe/Berlin), die nur als halber Tag zählen, zum Beispiel halbe Urlaubstage. Leere Liste, wenn es keine gibt

Arten (type)

Wert	Bedeutung in TimeMonkey
Vacation	Urlaub
Sickness	Krankheit
ChildSickness	Kind krank
CompensatoryTimeOff	Freizeitausgleich
ShortTimeWork	Kurzarbeit
FurtherEducation	Weiterbildung
ProfessionalSchool	Berufsschule
Holiday	Feiertag
MaternityProtection	Mutterschutz
ParentalLeave	Elternzeit

Antragsstatus (status)

Der Status ergibt sich aus dem jüngsten Antrag zur Abwesenheit:

Wert	Bedeutung
approved	Genehmigt – oder direkt eingetragen, ohne dass es einen Antrag gab. Auch nach einer abgelehnten Stornierung gilt die Abwesenheit wieder als approved.
requested	Beantragt, aber noch nicht entschieden
rejected	Antrag abgelehnt
cancellation_requested	Stornierung beantragt, aber noch nicht entschieden
cancelled	Stornierung genehmigt

Abwesenheiten in jedem Status

Die API liefert Abwesenheiten in jedem Status, also auch beantragte, abgelehnte und stornierte. Einen Filter nach Status gibt es nicht. Berücksichtige in deiner Auswertung deshalb das Feld status.

Beispiel

curl

Terminal

curl -s "https://api.time.monkeymed.de/api/v1/absences?from=2026-10-01&to=2026-10-31&type=Vacation" \
  -H "Authorization: Bearer $TIMEMONKEY_API_KEY"

JavaScript

absences.mjs

const params = {from: '2026-10-01', to: '2026-10-31', type: 'Vacation', limit: '500'};
const data = [];
let cursor = null;
do {
  const query = new URLSearchParams(params);
  if (cursor) query.set('cursor', cursor);
  const response = await fetch(`https://api.time.monkeymed.de/api/v1/absences?${query}`, {
    headers: {Authorization: `Bearer ${process.env.TIMEMONKEY_API_KEY}`},
  });
  const body = await response.json();
  if (!response.ok) {
    throw new Error(`${response.status} ${body.error.code}: ${body.error.message}`);
  }
  data.push(...body.data);
  cursor = body.nextCursor;
} while (cursor);
const approved = data.filter((absence) => absence.status === 'approved');
console.log(approved.length, 'genehmigte Urlaube im Oktober');

Python

absences.py

import os

import requests

params = {"from": "2026-10-01", "to": "2026-10-31", "type": "Vacation", "limit": 500}
data, cursor = [], None
while True:
    query = {**params}
    if cursor:
        query["cursor"] = cursor
    response = requests.get(
        "https://api.time.monkeymed.de/api/v1/absences",
        headers={"Authorization": f"Bearer {os.environ['TIMEMONKEY_API_KEY']}"},
        params=query,
        timeout=30,
    )
    response.raise_for_status()
    body = response.json()
    data.extend(body["data"])
    cursor = body["nextCursor"]
    if cursor is None:
        break
approved = [a for a in data if a["status"] == "approved"]
print(len(approved), "genehmigte Urlaube im Oktober")

200 OK

{
  "data": [
    {
      "id": "66c2d3e4f5a6b7c8d9e0f112",
      "employeeId": "650a1b2c3d4e5f6071829304",
      "type": "Vacation",
      "start": "2026-10-05T22:00:00.000Z",
      "end": "2026-10-08T22:00:00.000Z",
      "paid": true,
      "name": null,
      "status": "approved",
      "halfDays": ["2026-10-08"]
    },
    {
      "id": "66c2d3e4f5a6b7c8d9e0f113",
      "employeeId": "650a1b2c3d4e5f6071829305",
      "type": "Vacation",
      "start": "2026-10-25T23:00:00.000Z",
      "end": "2026-10-30T23:00:00.000Z",
      "paid": true,
      "name": null,
      "status": "requested",
      "halfDays": []
    }
  ],
  "nextCursor": null
}

Notizen, Dateianhänge, Vertretungen, Fortbildungspunkte, Angaben zum Kind und Details zur Elternzeit gibt die API nicht aus, siehe Datenschutz.