TimeMonkey REST-API

Beta Version 1.0.0-beta.1

Mit der TimeMonkey REST-API rufen externe Systeme die Daten deines Standorts ab, zum Beispiel deine Lohnbuchhaltung, ein BI-Werkzeug oder eigene Auswertungen. Die API ist rein lesend: Sie liefert Mitarbeiter, Stempel, Abwesenheiten, Schichten, Arbeitsbereiche sowie Tages-, Monats- und Jahresauswertungen mit Arbeitszeitkonto und Urlaubskonto, ändert aber nichts in TimeMonkey. Sie ist in TimeMonkey Pro enthalten.

Die REST-API ist in der Beta

Die REST-API befindet sich in der Beta (Version 1.0.0-beta.1). Endpunkte und Felder können sich bis zur Version 1.0.0 noch ändern. Plane deine Anbindung so, dass du sie bei Bedarf anpassen kannst, und behalte den Beta-Status und das Changelog im Blick.

Dein Feedback ist willkommen: Schreib dem Support, was gut funktioniert, was fehlt oder was dich stört – in der Webapp über Support unten in der linken Menüleiste und dann Support-Anfrage erstellen.

Auf einen Blick

Basis-URL https://api.time.monkeymed.de/api/v1
Zugriff Nur lesend, ausschließlich GET-Requests
Format JSON; Zeitpunkte in ISO 8601 (UTC), Dauern in Millisekunden
Authentifizierung API-Key als Authorization: Bearer tmk_live_…
Limits pro API-Key 60 Requests pro Minute und 1.000 pro Tag; bitte beachte die faire Nutzung
Voraussetzung TimeMonkey Pro oder die laufende Testphase
Spezifikation OpenAPI 3.0.3 als openapi.json
Version 1.0.0-beta.1 (Beta)

Was du abrufen kannst

Jeder API-Key gehört zu genau einem Standort und liefert nur dessen Daten. Welche Endpunkte ein Key nutzen darf, legst du beim Anlegen über Berechtigungen (Scopes) fest.

Endpunkt (`GET`)	Inhalt	Benötigter Scope
`/api/v1/company`	Name, aktuelle Adresse und Zeitzone des Standorts	keiner (jeder gültige Key)
`/api/v1/employees`	Mitarbeiter mit aktuellen Vertragswerten	`employees:read`
`/api/v1/employees/{id}`	Ein einzelner Mitarbeiter	`employees:read`
`/api/v1/stamps`	Stempelzeiten	`stamps:read`
`/api/v1/absences`	Abwesenheiten wie Urlaub oder Krankheit mit Antragsstatus	`absences:read`
`/api/v1/shifts`	Veröffentlichte Schichten	`shifts:read`
`/api/v1/areas`	Arbeitsbereiche der Schichtplanung	`shifts:read`
`/api/v1/evaluations/days`	Tagesauswertung je Mitarbeiter und Tag mit Soll, Gutschriften und Tagessaldo	`evaluations:read`
`/api/v1/evaluations/months`	Monatssaldo und Arbeitszeitkonto je Mitarbeiter und Monat	`evaluations:read`
`/api/v1/evaluations/years`	Stundenübertrag, Jahreskonto und Urlaubskonto je Mitarbeiter	`evaluations:read`
`/api/v1/openapi.json`	Maschinenlesbare Beschreibung der API	kein API-Key nötig

Schnellstart

1. API-Key in TimeMonkey anlegen

API-Keys verwalten Inhaber und Admins des Standorts in der Webapp.

Öffne Einstellungen und wechsle in den Reiter Schnittstellen.
Klicke in der Karte REST-API (Beta) auf API-Key erstellen.
Gib eine Bezeichnung ein (höchstens 64 Zeichen), zum Beispiel „Lohnbuchhaltung“. So erkennst du später, welches System den Key nutzt.
Wähle unter Berechtigungen (nur lesend) aus, welche Daten der Key abrufen darf: Mitarbeiter, Stempel, Abwesenheiten, Schichten & Bereiche oder Auswertungen. Mindestens eine Berechtigung ist nötig. Welche Berechtigung zu welchem Scope gehört, steht unter Authentifizierung und Scopes.
Klicke auf Erstellen.
Kopiere den angezeigten Key mit Kopieren und speichere ihn sicher, zum Beispiel in einem Passwort-Manager oder als geheime Umgebungsvariable deines Systems. Bestätige danach mit Ich habe den Key gespeichert.

Der API-Key wird nur ein einziges Mal angezeigt

TimeMonkey speichert den Key nicht im Klartext und kann ihn später nicht erneut anzeigen. Hast du ihn verloren, erstelle einen neuen Key und widerrufe den alten.

Ohne TimeMonkey Pro und außerhalb der Testphase lässt sich kein API-Key anlegen. Stattdessen öffnet sich der Hinweis zur Pro-Lizenz. Mehr dazu unter Lizenz und Rechnungen.

2. Ersten Request senden

Lies den Key im Terminal (Bash) ohne Anzeige ein und exportiere ihn als Umgebungsvariable. Führe dazu den folgenden Befehl aus, füge deinen Key ein und drücke die Eingabetaste. So landet der Key weder im Code noch in der Kommandozeilen-Historie:

Terminal
read -rs TIMEMONKEY_API_KEY && export TIMEMONKEY_API_KEY

Rufe dann den Standort ab. Der Endpunkt GET /api/v1/company funktioniert mit jedem gültigen Key, unabhängig von den gewählten Berechtigungen:

GET/api/v1/company

curl
JavaScript
Python

Terminal
curl -s https://api.time.monkeymed.de/api/v1/company \
  -H "Authorization: Bearer $TIMEMONKEY_API_KEY"

company.mjs (Node.js 18 oder neuer)
const response = await fetch('https://api.time.monkeymed.de/api/v1/company', {
  headers: {Authorization: `Bearer ${process.env.TIMEMONKEY_API_KEY}`},
});
if (!response.ok) {
  const {error} = await response.json();
  throw new Error(`${response.status} ${error.code}: ${error.message}`);
}
console.log(await response.json());

company.py
import os

import requests

response = requests.get(
    "https://api.time.monkeymed.de/api/v1/company",
    headers={"Authorization": f"Bearer {os.environ['TIMEMONKEY_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Die Antwort sieht zum Beispiel so aus:

200 OK
{
  "id": "64f1a2b3c4d5e6f708192a3b",
  "name": "Zahnarztpraxis Dr. Muster",
  "address": {
    "street": "Hauptstr.",
    "streetNo": "1",
    "zip": "10115",
    "city": "Berlin",
    "province": "DE-BE",
    "country": "DE"
  },
  "timeZone": "Europe/Berlin"
}

Bekommst du stattdessen einen Fehler, hilft die Übersicht Fehler und Rate-Limits weiter.

3. Daten abrufen

Mit der passenden Berechtigung rufst du nun Fachdaten ab, zum Beispiel alle Stempel im Oktober 2026 (Scope stamps:read):

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

Listen kommen seitenweise als { "data": [...], "nextCursor": "..." }. Wie du alle Seiten abholst und wie Datumsangaben, Zeitzonen und Dauern zu lesen sind, steht unter Grundlagen.

API-Keys verwalten

In der Karte REST-API (Beta) unter Einstellungen → Schnittstellen siehst du alle aktiven Keys des gewählten Standorts. Zu jedem Key stehen dort:

die Bezeichnung und die ersten Zeichen des Keys (zum Beispiel tmk_live_AbC…), damit du ihn wiedererkennst,
die gewählten Berechtigungen,
wann und von wem (E-Mail-Adresse) der Key erstellt wurde,
wann er zuletzt genutzt wurde oder „Noch nicht genutzt“. Der Zeitpunkt wird höchstens alle fünf Minuten aktualisiert.

Widerrufen: Über Widerrufen und die Bestätigung im Dialog sperrst du einen Key. Systeme, die ihn verwenden, erhalten sofort keinen Zugriff mehr. Ein Widerruf lässt sich nicht rückgängig machen.

Berechtigungen ändern: Die Berechtigungen eines bestehenden Keys lassen sich nicht bearbeiten. Erstelle einen neuen Key mit den gewünschten Berechtigungen, stelle dein System darauf um und widerrufe danach den alten Key.

Anzahl: Pro Standort sind höchstens 20 aktive API-Keys möglich. Widerrufene Keys zählen nicht mit.

Mehrere Standorte: Ein Key gilt immer nur für den Standort, in dem er angelegt wurde. Für weitere Standorte legst du jeweils eigene Keys an, nachdem du links unten zum gewünschten Standort gewechselt hast.

Weiterlesen

Authentifizierung, Scopes und Zugang – wie der Key übergeben wird und wann der Zugang gesperrt ist
Grundlagen – Pagination, Datumsformate, Zeitzone, Dauern und IDs
Endpunkte – alle Parameter, Antwortfelder und Beispiele
Fehler und Rate-Limits – Fehlercodes, Limits und Retry-After
Datenschutz – welche Daten die API nie ausgibt
Beta-Status und Changelog – was sich bis Version 1.0.0 noch ändern kann

Auf einen Blick​

Was du abrufen kannst​

Schnellstart​

1. API-Key in TimeMonkey anlegen​

2. Ersten Request senden​

3. Daten abrufen​

API-Keys verwalten​

Weiterlesen​