ConnectCloud Developers

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 of in, break, break-end, out)
  • time (string, required): Local time HH:MM in the tenant's time zone
  • employeeId (string): Empty or me for the caller
  • note (string): Stored on the segment the stamp opens
  • reason (string): Required for other people's time and for own days older than the tenant's selfEditDays

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 any
    • fraction (number): Share of the day the absence covers (1 or 0.5)
    • id (string): Id of the absence
    • status (string): State of the absence
    • typeId (string): Id of the absence type
  • actual (integer): Worked minutes
  • break (integer): Break minutes
  • counted (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 only
  • credit (integer): Minutes absences count as worked
  • date (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 day
    • autoEnded (boolean): HR ended the segment at midnight because nobody clocked out (setting autoEndAtMidnight). 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 created
    • createdBy (string): Who created the time entry (e-mail of the caller)
    • employeeId (string): Id of the employee
    • end (string (date-time)): Missing while running
    • endedForBreak (boolean): The segment was closed by starting a break
    • id (string): Id of the time entry
    • note (string): Note on the entry
    • source (string): clock: stamped, manual: entered by hand (one of clock, manual)
    • start (string (date-time)): Start of the segment
    • updatedAt (string (date-time)): When the time entry was last changed
    • updatedBy (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 of 0.5, 1)
    • name (string): Name of the holiday
  • running (boolean): A segment of the day is still open
  • target (integer): Scheduled minutes (minus holidays and unpaid absences)
  • violations (array of Violation): Working-time rule warnings (ArbZG); never blocking
    • breakMinutes (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 of break_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"}'

View as Markdown · Interactive reference · OpenAPI