Add one stamp (Kommen, Pause, Pause beenden, Gehen) to a day (own, or the team's with responsibility or hr:time:manage)
POST /api/hr/v1/time-stamps
Module: HR · operationId: applyTimeStamp · Tag: Working time · Auth: access token (Authorization: Bearer <accessToken>)
HR fits the stamp into the recorded time: in and break-end open a segment, break and
out close the open segment (also one from the day before – night shift). break inside a
finished segment splits it, and a following break-end moves the rest of it; at the exact
end of a segment break/out switch it between Pause and Gehen. A stamp that does not fit
fails with 409 and the code stamp_<reason> (stamp_already_open, stamp_inside_segment,
stamp_later_segment, stamp_no_break, stamp_no_open_segment, stamp_too_long,
stamp_unchanged) and field (time or kind). Like manual entries, a reason is required
for other people's time and own days older than selfEditDays; closed months fail with
409 period_closed, overlaps with 409 overlap, future times with 400. Returns the
rebuilt day.
Request body
application/json (required)
date(string (date), required): Day of the stamp (YYYY-MM-DD)kind(string, required): in = Kommen, break = Pause, break-end = Pause beenden, out = Gehen (one ofin,break,break-end,out)time(string, required): Local time HH:MM in the tenant's time zoneemployeeId(string): Empty ormefor the callernote(string): Stored on the segment the stamp opensreason(string): Required for other people's time and for own days older than the tenant'sselfEditDays
Example:
{
"date": "2026-11-17",
"kind": "break",
"reason": "Pause nachgetragen",
"time": "12:00"
}
Responses
- 200 The day after the stamp (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 404 Error (
application/json) - 409 Error (
application/json)
Fields of the 200 answer:
absence(object): The absence on the day, if anyfraction(number): Share of the day the absence covers (1 or 0.5)id(string): Id of the absencestatus(string): State of the absencetypeId(string): Id of the absence type
actual(integer): Worked minutesbreak(integer): Break minutescounted(boolean): The day lies before today (tenant time zone) and counts in the totals and the time account. Today shows its live target, actual and credit but is not counted yet; later days show their target onlycredit(integer): Minutes absences count as workeddate(string (date)): The day (YYYY-MM-DD)delta(integer): actual + credit − target, in minutes; 0 on days not counted (today and later)entries(array of TimeEntry): Time entries of the dayautoEnded(boolean): HR ended the segment at midnight because nobody clocked out (settingautoEndAtMidnight). It counts no working time until it is corrected; any change clears the mark.breakMinutes(integer): Break inside the segment in minutes (manual entries)createdAt(string (date-time)): When the time entry was createdcreatedBy(string): Who created the time entry (e-mail of the caller)employeeId(string): Id of the employeeend(string (date-time)): Missing while runningendedForBreak(boolean): The segment was closed by starting a breakid(string): Id of the time entrynote(string): Note on the entrysource(string): clock: stamped, manual: entered by hand (one ofclock,manual)start(string (date-time)): Start of the segmentupdatedAt(string (date-time)): When the time entry was last changedupdatedBy(string): Who last changed the time entry (e-mail of the caller)version(integer): Version for optimistic locking: send the version you read with a change (stale: 409 version_conflict)
holiday(Holiday)custom(boolean): A holiday of the tenant's own (omitted when false)date(string (date)): Date (YYYY-MM-DD)fraction(number): 1 for a full day, 0.5 for a half day (e.g. 24.12.) (one of0.5,1)name(string): Name of the holiday
running(boolean): A segment of the day is still opentarget(integer): Scheduled minutes (minus holidays and unpaid absences)violations(array of Violation): Working-time rule warnings (ArbZG); never blockingbreakMinutes(integer): Break that counts under §4 ArbZG: interruptions of 15 minutes or more plus booked breaks (break_6h, break_9h)code(string): auto_ended is no ArbZG rule: a segment HR ended at midnight whose times need checking (one ofbreak_6h,break_9h,max_10h,rest_11h,sunday_holiday,open_entry,auto_ended)entryId(string): The open or auto-ended entry (open_entry, auto_ended)excessMinutes(integer): Worked time above the maximum (max_10h)message(string): Human-readable text of the warning (German)requiredMinutes(integer): Limit of the rule: required break (30/45), maximum worked time (600) or minimum rest (660)restMinutes(integer): Rest since the previous work (rest_11h)since(string (date-time)): End of the previous work (rest_11h) or start of the open or auto-ended entry (open_entry, auto_ended)workedMinutes(integer): Worked time of the day (break_6h, break_9h, max_10h, sunday_holiday)
Example 200 answer:
{
"actual": 480,
"break": 30,
"counted": true,
"credit": 0,
"date": "2026-11-17",
"delta": 0,
"entries": [
{
"autoEnded": false,
"breakMinutes": 0,
"createdAt": "2026-11-18T07:02:00Z",
"createdBy": "sophie.huber@muster-it.example",
"employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
"end": "2026-11-17T11:00:00Z",
"endedForBreak": true,
"id": "1e3a5c7e-9a1c-4e3a-8c5e-9a1c3e5a7c40",
"source": "manual",
"start": "2026-11-17T06:30:00Z",
"updatedAt": "2026-11-18T07:02:00Z",
"updatedBy": "sophie.huber@muster-it.example",
"version": 1
},
{
"autoEnded": false,
"breakMinutes": 0,
"createdAt": "2026-11-18T07:03:00Z",
"createdBy": "sophie.huber@muster-it.example",
"employeeId": "e5a1c3d7-2b4f-4c6e-8a0b-1d3f5b7c9e02",
"end": "2026-11-17T15:00:00Z",
"endedForBreak": false,
"id": "3c5e7a9c-1e3a-4c5e-9a7c-1e3a5c7e9a41",
"source": "manual",
"start": "2026-11-17T11:30:00Z",
"updatedAt": "2026-11-18T07:03:00Z",
"updatedBy": "sophie.huber@muster-it.example",
"version": 1
}
],
"running": false,
"target": 480,
"violations": []
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/hr/v1/time-stamps' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"date":"2026-11-17","kind":"break","reason":"Pause nachgetragen","time":"12:00"}'