Timebutler API v2

Persönliche Zugangstoken

Als Alternative zum OAuth-2.0-Passwort-Flow können einzelne Benutzer persönliche Zugangstoken anlegen. Die Token sind langlebig, benannt, einzeln widerrufbar und auf einen Benutzer beschränkt — kein Passwort-Sharing und kein Refresh-Token-Wechsel nötig.

Token haben das Präfix tb_ gefolgt von einem undurchsichtigen, URL-sicheren Base64-String. Sie werden im Authorization-Header übergeben, genau wie ein normales Bearer-Token:

curl "https://app.timebutler.com/api/v2/timeentry/pendingcount" \
  -H "Authorization: Bearer tb_a1b2c3d4e5f6..."

Persönliches Token erstellen oder widerrufen →

Token ausstellen oder erneuern

{
  "access_token" : "eyJhbGciOiJSUzI1NiJ9...",
  "refresh_token" : "rt-a1b2c3d4e5f6...",
  "token_type" : "Bearer",
  "expires_in" : 3600,
  "scope" : "read"
}

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

{
  "error" : "invalid_grant",
  "error_description" : "Invalid username or password"
}

curl -X POST "https://app.timebutler.com/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=password&username=user%40example.com&password=s3cr3t&client_id=public'

curl -X POST "https://app.timebutler.com/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=refresh_token&refresh_token=550e8400-e29b-41d4-a716-446655440000&client_id=public'

curl -X POST "https://app.timebutler.com/api/v2/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'grant_type=mfa_totp&mfa_token=mfa-a1b2c3d4e5f6&totp_code=123456&client_id=public'

Offenen Abwesenheitsantrag genehmigen

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X POST "https://app.timebutler.com/api/v2/absence-requests/{id}/approve" \
  -H "Authorization: Bearer <token>"

Eigene Abwesenheitsanträge des Aufrufers auflisten (Alias)

[ {
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-requests" \
  -H "Authorization: Bearer <token>"

Neuen Abwesenheitsantrag erstellen

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X POST "https://app.timebutler.com/api/v2/absence-requests" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"absenceTypeId":"URL","startDate":"2025-08-01","endDate":"2025-08-05","halfDay":"morning","comments":"Holiday trip","substituteEmployeeId":"42"}'

Bestehenden Abwesenheitsantrag aktualisieren

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X PUT "https://app.timebutler.com/api/v2/absence-requests/{id}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"absenceTypeId":"URL","startDate":"2025-08-01","endDate":"2025-08-05","halfDay":"morning","comments":"Rescheduled trip","substituteEmployeeId":"42"}'

Abwesenheitsantrag löschen oder Stornierungsanfrage senden

{
  "id" : "12345",
  "result" : "deleted"
}

curl -X DELETE "https://app.timebutler.com/api/v2/absence-requests/{id}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Plans changed"}'

Eigene Abwesenheitsanträge des Aufrufers auflisten

[ {
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-requests/my" \
  -H "Authorization: Bearer <token>"

Offene Antragszahlen für das Team des Aufrufers

{
  "numberOfAbsenceRequests" : 3,
  "numberOfAbsenceRequestCancellations" : 1
}

curl -X GET "https://app.timebutler.com/api/v2/absence-requests/pending-count" \
  -H "Authorization: Bearer <token>"

Abwesenheitsanträge der unterstellten Mitarbeiter auflisten

[ {
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-requests/team" \
  -H "Authorization: Bearer <token>"

Offenen Abwesenheitsantrag ablehnen

{
  "id" : "12345",
  "type" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "halfDay" : "morning",
  "substitutePending" : false,
  "medicalCertificateProvided" : false,
  "employeeName" : "Maria Müller",
  "employeeId" : "42"
}

curl -X POST "https://app.timebutler.com/api/v2/absence-requests/{id}/reject" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Insufficient staffing during that period"}'

Abwesenheitsarten auflisten

[ {
  "id" : "URL",
  "name" : "Urlaub",
  "needsApproval" : true,
  "requiresMedicalCertificate" : false
} ]

curl -X GET "https://app.timebutler.com/api/v2/absence-types" \
  -H "Authorization: Bearer <token>"

Profil abrufen

{
  "id" : "42",
  "name" : "Maria Müller",
  "email" : "maria.mueller@example.com",
  "role" : "MANAGER",
  "department" : "Engineering",
  "branchOffice" : "Berlin",
  "country" : { },
  "avatar" : "/images/avatar/42/abc123.jpg?v=5",
  "isBusinessTripEnabled" : true,
  "isTimeTrackingEnabled" : true
}

curl -X GET "https://app.timebutler.com/api/v2/user/profile" \
  -H "Authorization: Bearer <token>"

Kategorien auflisten

{
  "categories" : [ {
    "id" : "7",
    "name" : "Internal project"
  } ],
  "defaultCategoryId" : "7",
  "isCategoryMandatory" : false
}

curl -X GET "https://app.timebutler.com/api/v2/categories" \
  -H "Authorization: Bearer <token>"

Mitarbeiter auflisten

[ {
  "id" : "42",
  "employeeNumber" : "MA-1024",
  "firstName" : "Maria",
  "lastName" : "Müller",
  "name" : "Maria Müller",
  "email" : "maria.mueller@example.com",
  "phone" : "+49 30 1234567",
  "mobile" : "+49 170 1234567",
  "role" : "USER",
  "department" : "Engineering",
  "costCenter" : "CC-100",
  "branchOffice" : "Berlin",
  "language" : "de_DE",
  "managerIds" : [ "17" ],
  "additionalInfo" : "Works part-time on Fridays",
  "employmentStartDate" : "2020-03-15",
  "employmentEndDate" : "2024-12-31",
  "dateOfBirth" : "1988-07-24",
  "active" : true
} ]

curl -X GET "https://app.timebutler.com/api/v2/employees" \
  -H "Authorization: Bearer <token>"

Projekte auflisten

{
  "projects" : [ {
    "id" : "5",
    "name" : "Website Relaunch",
    "isFavorite" : true
  } ],
  "defaultProjectId" : "5",
  "isProjectMandatory" : true
}

curl -X GET "https://app.timebutler.com/api/v2/projects" \
  -H "Authorization: Bearer <token>"

Dienstgang beenden

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false,
  "startOnlyOnTerminal" : false,
  "pauseOnlyOnTerminal" : false,
  "stopOnlyOnTerminal" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/business-trip-end" \
  -H "Authorization: Bearer <token>"

Dienstgang starten

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false,
  "startOnlyOnTerminal" : false,
  "pauseOnlyOnTerminal" : false,
  "stopOnlyOnTerminal" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/business-trip-start" \
  -H "Authorization: Bearer <token>"

Stempeluhr abbrechen

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false,
  "startOnlyOnTerminal" : false,
  "pauseOnlyOnTerminal" : false,
  "stopOnlyOnTerminal" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/cancel" \
  -H "Authorization: Bearer <token>"

Stempeluhr-Status abrufen

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false,
  "startOnlyOnTerminal" : false,
  "pauseOnlyOnTerminal" : false,
  "stopOnlyOnTerminal" : false
}

curl -X GET "https://app.timebutler.com/api/v2/time-clock/status" \
  -H "Authorization: Bearer <token>"

Stempeluhr pausieren

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false,
  "startOnlyOnTerminal" : false,
  "pauseOnlyOnTerminal" : false,
  "stopOnlyOnTerminal" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/pause" \
  -H "Authorization: Bearer <token>"

Stempeluhr fortsetzen

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false,
  "startOnlyOnTerminal" : false,
  "pauseOnlyOnTerminal" : false,
  "stopOnlyOnTerminal" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/resume" \
  -H "Authorization: Bearer <token>"

Stempeluhr starten

{
  "status" : "running",
  "startTimestamp" : 1753700400000,
  "pauseTimestamp" : 1753714800000,
  "workTimeElapsedSeconds" : 14400,
  "breakElapsedSeconds" : 0,
  "accumulatedBreakSeconds" : 1800,
  "waitSeconds" : 0,
  "isBusinessTripActive" : false,
  "startOnlyOnTerminal" : false,
  "pauseOnlyOnTerminal" : false,
  "stopOnlyOnTerminal" : false
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/start" \
  -H "Authorization: Bearer <token>"

Stempeluhr stoppen und speichern

{
  "outcome" : "saved",
  "id" : "98765",
  "workedMinutes" : 450,
  "breakMinutes" : 30,
  "breakRegulationApplied" : true,
  "breakRegulationIgnored" : false,
  "breakRegulation" : {
    "hasNoRemedy" : false,
    "obligatory" : false,
    "correctionWorkMinutes" : 30,
    "correctionBreakMinutes" : 30,
    "resultingWorkMinutes" : 450,
    "resultingBreakMinutes" : 30,
    "detailText" : "Required change: working time -0:30, break +0:30"
  }
}

curl -X POST "https://app.timebutler.com/api/v2/time-clock/stop" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"projectId":5,"categoryId":7,"remarks":"Code review","breakRegulation":"apply"}'

Stornierungsantrag genehmigen

{
  "id" : "12345",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "cancelComments" : "Plans changed"
}

curl -X POST "https://app.timebutler.com/api/v2/cancellation-requests/{id}/approve" \
  -H "Authorization: Bearer <token>"

Offene Stornierungsanträge auflisten

[ {
  "id" : "12345",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "cancelComments" : "Plans changed"
} ]

curl -X GET "https://app.timebutler.com/api/v2/cancellation-requests" \
  -H "Authorization: Bearer <token>"

Anzahl offener Stornierungsanträge abrufen

{
  "numberOfCancellationRequests" : 2
}

curl -X GET "https://app.timebutler.com/api/v2/cancellation-requests/pending-count" \
  -H "Authorization: Bearer <token>"

Stornierungsantrag ablehnen

{
  "id" : "12345",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending",
  "cancelComments" : "Plans changed"
}

curl -X POST "https://app.timebutler.com/api/v2/cancellation-requests/{id}/reject" \
  -H "Authorization: Bearer <token>"

Vertretungsanfrage annehmen

{
  "id" : "12345",
  "employeeId" : "7",
  "employeeName" : "Anna Bauer",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/substitute-requests/{id}/accept" \
  -H "Authorization: Bearer <token>"

Anzahl offener Vertretungsanfragen abrufen

{
  "numberOfSubstituteRequests" : 1
}

curl -X GET "https://app.timebutler.com/api/v2/substitute-requests/pending-count" \
  -H "Authorization: Bearer <token>"

Vertretungsanfragen auflisten

[ {
  "id" : "12345",
  "employeeId" : "7",
  "employeeName" : "Anna Bauer",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending"
} ]

curl -X GET "https://app.timebutler.com/api/v2/substitute-requests" \
  -H "Authorization: Bearer <token>"

Vertretungsanfrage ablehnen

{
  "id" : "12345",
  "employeeId" : "7",
  "employeeName" : "Anna Bauer",
  "absenceType" : "URL",
  "startDate" : "2025-08-01",
  "endDate" : "2025-08-05",
  "days" : 4.0,
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/substitute-requests/{id}/reject" \
  -H "Authorization: Bearer <token>"

Vertretungsmitarbeiter auflisten

[ {
  "id" : "42",
  "name" : "Thomas Schmidt",
  "department" : "Engineering"
} ]

curl -X GET "https://app.timebutler.com/api/v2/substitute-employees" \
  -H "Authorization: Bearer <token>"

Zeiteintrag löschen

{
  "id" : "12345",
  "result" : "deleted"
}

curl -X DELETE "https://app.timebutler.com/api/v2/time-entries/{id}" \
  -H "Authorization: Bearer <token>"

Eigene Zeiteinträge des Aufrufers auflisten

[ {
  "id" : "98765",
  "date" : "2025-07-28",
  "startTime" : "08:00",
  "endTime" : "17:00",
  "workedMinutes" : 480,
  "breakMinutes" : 60,
  "projectId" : "17",
  "project" : "Website Relaunch",
  "categoryId" : "4",
  "category" : "Internal project",
  "status" : "done",
  "autoStopped" : false,
  "remarks" : "Sprint planning"
} ]

curl -X GET "https://app.timebutler.com/api/v2/time-entries/my" \
  -H "Authorization: Bearer <token>"

Anzahl ausstehender Zeiteinträge abrufen

{
  "numberOfTimeEntries" : 5
}

curl -X GET "https://app.timebutler.com/api/v2/time-entries/pending-count" \
  -H "Authorization: Bearer <token>"

Abgeschlossenen Zeiteintrag einreichen

{
  "id" : "98765",
  "workedMinutes" : 480,
  "breakMinutes" : 30
}

curl -X POST "https://app.timebutler.com/api/v2/time-tracking/clock-entry" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"startTimestamp":1753700400000,"endTimestamp":1753729200000,"pauseSeconds":1800,"projectId":5,"remarks":"Sprint planning"}'

Abwesenheitszusammenfassung abrufen

{
  "vacationDaysRemaining" : 12.5,
  "vacationDaysTotal" : 30.0,
  "illnessDaysTaken" : 3.0
}

curl -X GET "https://app.timebutler.com/api/v2/time-tracking/time-off-summary" \
  -H "Authorization: Bearer <token>"

Heutige Arbeitszusammenfassung abrufen

{
  "commitmentMinutes" : 2400,
  "workedMinutes" : 2280,
  "remainingMinutes" : 120,
  "percentDone" : 95,
  "breakMinutes" : 300
}

curl -X GET "https://app.timebutler.com/api/v2/time-tracking/work-summary" \
  -H "Authorization: Bearer <token>"

Zeiterfassungsantrag genehmigen

{
  "id" : "98765",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "date" : "2025-07-28",
  "startTime" : "08:00",
  "endTime" : "17:00",
  "workedMinutes" : 480,
  "breakMinutes" : 60,
  "project" : "Website Relaunch",
  "category" : "Internal project",
  "remarks" : "Sprint planning",
  "requestType" : "manual",
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/time-entry-requests/{id}/approve" \
  -H "Authorization: Bearer <token>"

Ausstehende Zeiterfassungsanträge auflisten

[ {
  "id" : "98765",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "date" : "2025-07-28",
  "startTime" : "08:00",
  "endTime" : "17:00",
  "workedMinutes" : 480,
  "breakMinutes" : 60,
  "project" : "Website Relaunch",
  "category" : "Internal project",
  "remarks" : "Sprint planning",
  "requestType" : "manual",
  "status" : "pending"
} ]

curl -X GET "https://app.timebutler.com/api/v2/time-entry-requests" \
  -H "Authorization: Bearer <token>"

Zeiterfassungsantrag ablehnen

{
  "id" : "98765",
  "employeeId" : "42",
  "employeeName" : "Maria Müller",
  "date" : "2025-07-28",
  "startTime" : "08:00",
  "endTime" : "17:00",
  "workedMinutes" : 480,
  "breakMinutes" : 60,
  "project" : "Website Relaunch",
  "category" : "Internal project",
  "remarks" : "Sprint planning",
  "requestType" : "manual",
  "status" : "pending"
}

curl -X POST "https://app.timebutler.com/api/v2/time-entry-requests/{id}/reject" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Insufficient staffing during that period"}'