Timdio API

Base URLs

Die externe Timdio API ist versioniert. Verwende für neue Integrationen die v1-Base-URL.

Authentifizierung

API-Secrets werden im Adminbereich erstellt, nur einmal angezeigt und serverseitig gehasht gespeichert. Speichere Secrets sicher und verwende sie niemals in Browser-Frontends oder öffentlichen Repositories.

Authorization: Bearer <TIMDIO_API_SECRET>
X-Timdio-Secret: <TIMDIO_API_SECRET>
X-Timdio-Api-Key: <TIMDIO_API_SECRET>

Der bevorzugte Header ist Authorization: Bearer. Die alternativen Header sind für Integrationen gedacht, die Bearer-Header nicht sauber setzen können.

Erste Anfrage

curl -H "Authorization: Bearer $TIMDIO_API_SECRET" \
  https://api.timdio.com/api/v1/health

{
  "ok": true,
  "service": "Timdio API",
  "version": "v1"
}

Endpunktübersicht

Die folgenden Endpunkte sind im aktuellen Source vorhanden. Geschützte Endpunkte benötigen ein aktives API-Secret und passende Scopes.

Status & Metadaten

Stammdaten

Zeitdaten, Reports & Exporte

Zeitbuchungen

GET /api/v1/time-entries liefert Zeitbuchungen für einen Zeitraum. Der Zeitraum ist auf maximal 370 Tage pro Request begrenzt.

curl -H "Authorization: Bearer $TIMDIO_API_SECRET" \
  "https://api.timdio.com/api/v1/time-entries?from_date=2026-05-01&to_date=2026-05-31&limit=500&offset=0"

{
  "items": [
    {
      "id": "entry_123",
      "employee_id": "emp_123",
      "employee_name": "Max Mustermann",
      "started_at": "2026-05-01T08:00:00+02:00",
      "ended_at": "2026-05-01T16:30:00+02:00",
      "duration_minutes": 510,
      "break_minutes": 30,
      "net_minutes": 480,
      "work_context_name": "Filiale Berlin",
      "work_context_code": "BER-01",
      "work_context_type": "location",
      "cost_center": "KST-100",
      "cost_center_id": "ctx_123",
      "proof_status": "ok",
      "changed_at": "2026-05-01T16:31:00+02:00"
    }
  ],
  "pagination": { "limit": 500, "offset": 0, "total": 1, "has_more": false }
}

Arbeitskontexte

GET /api/v1/work-contexts liefert aktive Arbeitskontexte wie Standorte, Filialen, Projekte, Abteilungen, Baustellen oder Kostenstellen. Archivierte Kontexte können über archived=true oder active=false abgefragt werden.

Unterstützte Filter: type, active, archived, cost_center, parent_id, limit und offset.

Kostenstellen

Kostenstellen können für Controlling, Lohnvorbereitung, Projektabrechnung und externe Validierung genutzt werden. Historische Buchungen bleiben auch bei archivierten Kostenstellen auswertbar, weil Zeitbuchungen weiterhin ihre Kontext- und Kostenstelleninformationen tragen.

GET /api/v1/cost-centers unterstützt active, archived, code, q, parent_id, limit und offset.

GET /api/v1/reports/cost-centers liefert Summen je Kostenstelle und Zeitraum. Der Report akzeptiert entweder from_date und to_date oder year und month.

curl -H "Authorization: Bearer $TIMDIO_API_SECRET" \
  "https://api.timdio.com/api/v1/reports/cost-centers?from_date=2026-05-01&to_date=2026-05-31"

Monatsdaten und Exporte

GET /api/v1/month-data stellt Monatsdaten je Mitarbeiter bereit. Der Endpunkt nutzt year, month, optional user_id sowie limit und offset.

GET /api/v1/export-profiles zeigt verfügbare Exportprofile für Lohnbüro, Steuerberater und Controlling. GET /api/v1/exports/history liefert die Exporthistorie; GET /api/v1/exports/history/{export_id} liefert Details zu einem Exportlauf.

Webhooks

Webhooks werden im Adminbereich konfiguriert und sind paketabhängig. Timdio sendet JSON-Payloads per HTTPS an aktive Ziel-URLs. Ein Zielendpunkt muss mit einem 2xx-Status antworten.

Event-Namen

Header

X-Timdio-Event: time_entry.changed
X-Timdio-Timestamp: 1777629600
X-Timdio-Signature: sha256=<hmac_sha256>

Die Signatur wird aus Timestamp und Payload mit dem Webhook-Secret gebildet. Prüfe Timestamp und Signatur serverseitig, um Replay-Angriffe zu erschweren.

{
  "event": "time_entry.changed",
  "event_id": "evt_123",
  "occurred_at": "2026-05-01T12:00:00+02:00",
  "company_id": "company_123",
  "resource_type": "time_entry",
  "resource_id": "entry_123",
  "data": {
    "employee_id": "emp_123",
    "cost_center": "KST-100"
  }
}

Fehlercodes

FastAPI-Validierungen können ein strukturiertes detail-Array liefern. Fachliche Fehler werden als klare Fehlermeldung im Response-Body zurückgegeben.

Sicherheit, Limits und große Datenmengen

• API-Key geheim halten und nur serverseitig verwenden.
• Nur benötigte Scopes vergeben und Secrets regelmäßig rotieren.
• HTTPS für API und Webhook-Ziele verwenden.
• Deaktivierte Dienstleister, alte Integrationen und nicht mehr benötigte Secrets entfernen.
• Große Zeiträume vermeiden, Pagination nutzen und Monatsabfragen bevorzugen.
• Für hohe Volumina, individuelle Limits oder BI-Synchronisationen den Business-Support kontaktieren.

Aktuelle Pagination-Limits: Mitarbeiter, Arbeitskontexte und Kostenstellen bis 500 Datensätze pro Seite, Zeitbuchungen bis 2000 Datensätze pro Seite, Monatsdaten bis 500 Mitarbeiter pro Seite und Exporthistorie bis 200 Einträge pro Seite.