Mitarbeiter abrufen

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

Die Mitarbeiter-Endpunkte liefern Stammdaten und die vertraglichen Arbeitszeiten der Mitarbeiter deines Standorts. Beide brauchen den Scope employees:read (Berechtigung Mitarbeiter). Private Angaben wie Geburtsdatum, private Kontaktdaten oder PIN gibt die API nie aus, siehe Datenschutz.

Mitarbeiter auflisten

GET/api/v1/employeesScopeemployees:read

GET /api/v1/employees liefert standardmäßig alle aktiven Mitarbeiter, sortiert nach id und seitenweise (siehe Pagination). Benötigter Scope: employees:read.

Parameter

Name	Pflicht	Typ	Beschreibung
status	nein	active, inactive oder all	Welche Mitarbeiter geliefert werden. Standard: active
include	nein	contractHistory	Liefert zusätzlich alle Vertragsstände im Feld contractHistory
limit	nein	Ganzzahl 1–500	Einträge pro Seite. Standard: 100
cursor	nein	String	Wert von nextCursor aus der vorherigen Antwort

Beispiel

curl

Terminal

curl -s "https://api.time.monkeymed.de/api/v1/employees?status=all" \
  -H "Authorization: Bearer $TIMEMONKEY_API_KEY"

JavaScript

employees.mjs

const query = new URLSearchParams({status: 'all'});
const response = await fetch(`https://api.time.monkeymed.de/api/v1/employees?${query}`, {
  headers: {Authorization: `Bearer ${process.env.TIMEMONKEY_API_KEY}`},
});
const {data, nextCursor} = await response.json();
for (const employee of data) {
  const weekly = employee.contract.weeklyMs;
  console.log(employee.prename, employee.name, weekly !== null ? weekly / 3600000 : '-', 'h/Woche');
}

Python

employees.py

import os

import requests

response = requests.get(
    "https://api.time.monkeymed.de/api/v1/employees",
    headers={"Authorization": f"Bearer {os.environ['TIMEMONKEY_API_KEY']}"},
    params={"status": "all"},
    timeout=30,
)
response.raise_for_status()
for employee in response.json()["data"]:
    weekly = employee["contract"]["weeklyMs"]
    print(employee["prename"], employee["name"], weekly / 3_600_000 if weekly else "-", "h/Woche")

200 OK

{
  "data": [
    {
      "id": "650a1b2c3d4e5f6071829304",
      "prename": "Anna",
      "name": "Beispiel",
      "status": "active",
      "employedSince": "2021-03-31T22:00:00.000Z",
      "employedUntil": null,
      "mail": "anna.beispiel@example.com",
      "tags": ["Prophylaxe", "Assistenz"],
      "mainTag": null,
      "contract": {
        "type": "weeklyHours",
        "weeklyMs": 138600000,
        "monthlyMs": null,
        "dailyMs": {
          "mon": 28800000,
          "tue": 28800000,
          "wed": 28800000,
          "thu": 28800000,
          "fri": 23400000,
          "sat": 0,
          "sun": 0
        },
        "annualVacationDays": 30,
        "dailyDeductionMs": 0
      }
    }
  ],
  "nextCursor": null
}

Einen Mitarbeiter abrufen

GET/api/v1/employees/{id}Scopeemployees:read

GET /api/v1/employees/{id} liefert einen einzelnen Mitarbeiter in derselben Form wie ein Eintrag der Liste, unabhängig davon, ob er aktiv oder inaktiv ist. Benötigter Scope: employees:read. Gibt es am Standort keinen Mitarbeiter mit dieser ID, antwortet die API mit 404 not_found.

Parameter

Name	Ort	Pflicht	Typ	Beschreibung
id	Pfad	ja	ID (24 Hex-Zeichen)	ID des Mitarbeiters
include	Abfrage	nein	contractHistory	Liefert zusätzlich alle Vertragsstände im Feld contractHistory

Beispiel mit Vertragshistorie

curl

Terminal

curl -s "https://api.time.monkeymed.de/api/v1/employees/650a1b2c3d4e5f6071829304?include=contractHistory" \
  -H "Authorization: Bearer $TIMEMONKEY_API_KEY"

JavaScript

employee.mjs

const id = '650a1b2c3d4e5f6071829304';
const response = await fetch(
  `https://api.time.monkeymed.de/api/v1/employees/${id}?include=contractHistory`,
  {headers: {Authorization: `Bearer ${process.env.TIMEMONKEY_API_KEY}`}},
);
const employee = await response.json();
console.log(employee.contractHistory.weeklyMs);

Python

employee.py

import os

import requests

employee_id = "650a1b2c3d4e5f6071829304"
response = requests.get(
    f"https://api.time.monkeymed.de/api/v1/employees/{employee_id}",
    headers={"Authorization": f"Bearer {os.environ['TIMEMONKEY_API_KEY']}"},
    params={"include": "contractHistory"},
    timeout=30,
)
response.raise_for_status()
print(response.json()["contractHistory"]["weeklyMs"])

200 OK (gekürzt)

{
  "id": "650a1b2c3d4e5f6071829304",
  "prename": "Anna",
  "name": "Beispiel",
  "status": "active",
  "contract": { "type": "weeklyHours", "weeklyMs": 138600000, "...": "..." },
  "contractHistory": {
    "dailyHours": [
      {
        "validFrom": "2021-03-31T22:00:00.000Z",
        "value": {
          "mon": 28800000, "tue": 28800000, "wed": 28800000, "thu": 28800000,
          "fri": 28800000, "sat": 0, "sun": 0,
          "type": "weeklyHours",
          "monthlyMs": null
        }
      },
      {
        "validFrom": "2025-12-31T23:00:00.000Z",
        "value": {
          "mon": 28800000, "tue": 28800000, "wed": 28800000, "thu": 28800000,
          "fri": 23400000, "sat": 0, "sun": 0,
          "type": "weeklyHours",
          "monthlyMs": null
        }
      }
    ],
    "weeklyMs": [
      { "validFrom": "2021-03-31T22:00:00.000Z", "value": 144000000 },
      { "validFrom": "2025-12-31T23:00:00.000Z", "value": 138600000 }
    ],
    "monthlyMs": [],
    "annualVacationDays": [
      { "validFrom": "2021-03-31T22:00:00.000Z", "value": 30 }
    ],
    "dailyDeductionMs": []
  }
}

Antwortfelder

Feld	Typ	Beschreibung
id	String	ID des Mitarbeiters
prename	String	Vorname
name	String	Nachname
status	active oder inactive	Ob der Mitarbeiter aktiv ist
employedSince	Zeitpunkt oder null	Beginn des Arbeitsverhältnisses
employedUntil	Zeitpunkt oder null	Ende des Arbeitsverhältnisses, falls eingetragen
mail	String oder null	Berufliche E-Mail-Adresse des Mitarbeiters, falls hinterlegt
tags	Liste von Strings	Die Gruppen des Mitarbeiters, zum Beispiel „Prophylaxe“
mainTag	String oder null	Hauptgruppe des Mitarbeiters (älteres Feld, in der Webapp derzeit nicht pflegbar, meist null)
contract	Objekt	Die zum Abfragezeitpunkt gültigen Vertragswerte, siehe unten
contractHistory	Objekt	Nur mit include=contractHistory: alle Vertragsstände, siehe unten

Vertragswerte (contract)

Alle Zeiten sind Dauern in Millisekunden (siehe Dauern). Felder ohne hinterlegten Wert sind null.

Feld	Typ	Beschreibung
type	weeklyHours, monthlyHours oder null	Art der vertraglichen Arbeitszeit: Wochenstunden oder Monatsstunden
weeklyMs	Zahl oder null	Wochenstunden. Ist kein positiver Wochenwert hinterlegt, ist es die Summe der Stunden je Wochentag (dailyMs). Bei Monatsverträgen wird nicht umgerechnet.
monthlyMs	Zahl oder null	Monatliche Arbeitsstunden
dailyMs	Objekt oder null	Vertragliche Stunden je Wochentag mit den Schlüsseln mon, tue, wed, thu, fri, sat, sun
annualVacationDays	Zahl oder null	Urlaubsanspruch in Tagen (keine Millisekunden)
dailyDeductionMs	Zahl oder null	Die Arbeitszeitpauschale je Arbeitstag, zum Beispiel für Umziehzeiten. Positive Werte werden gutgeschrieben, negative abgezogen. In der Tagesauswertung ist die Pauschale bereits enthalten, also nicht erneut addieren: in workedMs nur an vollständigen Tagen mit Arbeitszeit über 0, in plannedMs an Tagen mit geplanter Schicht.

Vertragshistorie (contractHistory)

Mit include=contractHistory liefert die API zusätzlich alle hinterlegten Vertragsstände. Jede Reihe ist eine Liste von Einträgen { "validFrom": Zeitpunkt, "value": Wert }, aufsteigend nach validFrom sortiert. Ein Wert gilt ab validFrom bis zum nächsten Eintrag.

Feld	Inhalt von value
dailyHours	Stunden je Wochentag (mon bis sun) sowie type und monthlyMs dieses Vertragsstands
weeklyMs	Die wirksamen Wochenstunden an jedem Zeitpunkt, an dem sich Wochen- oder Tageswerte ändern, mit derselben Regel wie contract.weeklyMs
monthlyMs	Monatliche Arbeitsstunden
annualVacationDays	Urlaubsanspruch in Tagen
dailyDeductionMs	Arbeitszeitpauschale je Arbeitstag

Die Vertragshistorie entspricht den Einträgen, die du in der Personalakte unter Wert hinzufügen mit einem Datum unter Eintrag gültig ab anlegst.