Jahresauswertung 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/evaluations/yearsScopeevaluations:read

GET /api/v1/evaluations/years liefert für jeden Mitarbeiter das Arbeitszeitkonto eines Jahres – Übertrag aus dem Vorjahr, Über- und Minusstunden des Jahres, Kontostand – und das Urlaubskonto mit Anspruch, Resturlaub, genommenen, geplanten und noch verfügbaren Tagen. Die Werte entsprechen der Jahresauswertung und der Urlaubsübersicht in TimeMonkey. Benötigter Scope: evaluations:read (Berechtigung Auswertungen).

• Das Jahr darf nicht in der Zukunft liegen. Das laufende Jahr zählt bis heute.
• Enthalten sind nur Mitarbeiter, die in diesem Jahr ausgewertet werden: ab Vertragsbeginn bis zum Austritt.
• Enthalten sind aktive und inaktive Mitarbeiter.
• Die Einträge sind nach employeeId sortiert.

Rechenintensive Abfrage

TimeMonkey berechnet das ganze Jahr bei jedem Abruf vollständig neu. Den Stand des Kontos im laufenden Monat bekommst du auch über die Monatsauswertung (accountMs).

• Rufe die Jahresauswertung höchstens einmal täglich ab; für die meisten Zwecke genügt einmal pro Woche.
• Eine Seite kann weniger Einträge als limit enthalten, weil die Rechenzeit pro Seite begrenzt ist. Folge immer nextCursor, bis er null ist.
• Bitte beachte die Hinweise zur fairen Nutzung.

Parameter

Name	Pflicht	Typ	Beschreibung
year	ja	Ganzzahl	Jahr, zum Beispiel 2026. Nicht in der Zukunft
employeeId	nein	ID	Nur dieser Mitarbeiter
limit	nein	Ganzzahl 1–500	Einträge pro Seite, höchstens. Standard: 100
cursor	nein	String	Wert von nextCursor aus der vorherigen Antwort

Antwortfelder

Stunden sind Dauern in Millisekunden (siehe Dauern), Urlaub wird in Tagen angegeben, auf zwei Nachkommastellen gerundet.

Feld	Typ	Beschreibung
year	Ganzzahl	Jahr
employeeId	String	ID des Mitarbeiters
through	Datum YYYY-MM-DD	Letzter eingerechneter Tag. Im laufenden Jahr ist das heute, sonst der 31. Dezember
carryoverMs	Zahl	Stundenübertrag aus dem Vorjahr
balanceMs	Zahl	Über- bzw. Minusstunden des Jahres bis through (Summe der Monatssalden)
accountMs	Zahl	Arbeitszeitkonto am Ende von through = carryoverMs + balanceMs
vacation	Objekt	Urlaubskonto, Felder siehe unten

Felder von vacation:

Feld	Beschreibung
annualDays	Urlaubsanspruch des Jahres
carryoverDays	Resturlaub aus dem Vorjahr
carryoverExpiresOn	Verfallsdatum des Resturlaubs (YYYY-MM-DD) oder null. Eine Elternzeit kann den Verfall verschieben; angegeben ist das wirksame Datum
usedDays	Bis heute genommene Urlaubstage aus dem Jahresanspruch
usedCarryoverDays	Bis heute genommene Urlaubstage aus dem Resturlaub
scheduledDays	Ab morgen eingetragene Urlaubstage aus dem Jahresanspruch
scheduledCarryoverDays	Ab morgen eingetragene Urlaubstage aus dem Resturlaub
availableDays	Noch verfügbare Tage aus dem Jahresanspruch
availableCarryoverDays	Noch verfügbarer Resturlaub; 0 nach dem Verfallsdatum

Gezählt werden nur bezahlte, genehmigte Urlaubstage; ein halber Tag zählt 0.5. Urlaub verbraucht zuerst den Resturlaub, solange er nicht verfallen ist.

Beispiel

curl

Terminal

curl -s "https://api.time.monkeymed.de/api/v1/evaluations/years?year=2026&limit=500" \
  -H "Authorization: Bearer $TIMEMONKEY_API_KEY"

JavaScript

evaluation-years.mjs

const years = [];
let cursor;
do {
  const query = new URLSearchParams({year: '2026', limit: '500', ...(cursor && {cursor})});
  const response = await fetch(`https://api.time.monkeymed.de/api/v1/evaluations/years?${query}`, {
    headers: {Authorization: `Bearer ${process.env.TIMEMONKEY_API_KEY}`},
  });
  const page = await response.json();
  years.push(...page.data);
  cursor = page.nextCursor;
} while (cursor);

for (const entry of years) {
  const vacationLeft = entry.vacation.availableDays + entry.vacation.availableCarryoverDays;
  console.log(`${entry.employeeId}: Konto ${(entry.accountMs / 3600000).toFixed(2)} h, Resturlaub ${vacationLeft} Tage`);
}

Python

evaluation_years.py

import os

import requests

years, cursor = [], None
while True:
    params = {"year": 2026, "limit": 500}
    if cursor:
        params["cursor"] = cursor
    response = requests.get(
        "https://api.time.monkeymed.de/api/v1/evaluations/years",
        headers={"Authorization": f"Bearer {os.environ['TIMEMONKEY_API_KEY']}"},
        params=params,
        timeout=60,
    )
    response.raise_for_status()
    page = response.json()
    years += page["data"]
    cursor = page["nextCursor"]
    if not cursor:
        break

for entry in years:
    vacation_left = entry["vacation"]["availableDays"] + entry["vacation"]["availableCarryoverDays"]
    print(f"{entry['employeeId']}: Konto {entry['accountMs'] / 3_600_000:.2f} h, Resturlaub {vacation_left} Tage")

200 OK

{
  "data": [
    {
      "year": 2026,
      "employeeId": "650a1b2c3d4e5f6071829304",
      "through": "2026-11-09",
      "carryoverMs": 36000000,
      "balanceMs": 10800000,
      "accountMs": 46800000,
      "vacation": {
        "annualDays": 30,
        "carryoverDays": 4,
        "carryoverExpiresOn": "2026-03-31",
        "usedDays": 22,
        "usedCarryoverDays": 4,
        "scheduledDays": 5,
        "scheduledCarryoverDays": 0,
        "availableDays": 3,
        "availableCarryoverDays": 0
      }
    }
  ],
  "nextCursor": null
}

Im Beispiel hat die Mitarbeiterin 10 Überstunden aus 2025 übernommen und 2026 bis zum 9. November 3 weitere aufgebaut; ihr Konto steht bei 13 Stunden. Von 30 Urlaubstagen hat sie 22 genommen und 5 für Dezember eingetragen, 3 sind noch frei. Die 4 Resturlaubstage aus dem Vorjahr hat sie vor dem Verfall Ende März genommen.