Workdays

A workday represents a single calendar day of work for an employee. It aggregates all timespans for that day and provides summary information like total work duration and break duration.

The Workday Object

  • Name
    id
    Type
    string (UUID)
    Description

    Unique identifier for the workday.

  • Name
    created_at
    Type
    string (ISO 8601)
    Description

    Timestamp when the workday was created.

  • Name
    modified_at
    Type
    string (ISO 8601)
    Description

    Timestamp when the workday was last modified.

  • Name
    workmonth_id
    Type
    string (UUID)
    Description

    The workmonth this workday belongs to. Read-only.

  • Name
    checkin
    Type
    string (ISO 8601)
    Description

    Earliest check-in time of the day. Read-only.

  • Name
    checkout
    Type
    string (ISO 8601) or null
    Description

    Latest check-out time of the day, or null if still working. Read-only.

  • Name
    work_duration
    Type
    integer
    Description

    Total working time in seconds. Computed from check-in, check-out, and break duration; remains 0 until the employee checks out. Read-only.

  • Name
    break_duration
    Type
    integer
    Description

    Total break time in seconds. Read-only.

  • Name
    note
    Type
    string or null
    Description

    Administrative note for the workday.

  • Name
    short_break_policy
    Type
    string
    Description

    The break policy applied to this workday, taken from the employee's break settings. One of disabled, enabled_always, enabled_15min, or enabled_never. Read-only.

GET/api/v2/timestamps/workdays/

List all Workdays

Retrieve a paginated list of workdays.

Query Parameters

  • Name
    daterange
    Type
    string
    Description

    Filter by date range: YYYY-MM-DD|YYYY-MM-DD. Open-ended ranges are supported by omitting one side, e.g. 2024-06-01| or |2024-06-30.

  • Name
    ids
    Type
    string
    Description

    Restrict the result set to specific workdays by passing a pipe-separated list of workday UUIDs. Invalid UUIDs are silently ignored.

  • Name
    token
    Type
    string
    Description

    Filter by employee RFID token, pipe-separated.

  • Name
    filter
    Type
    string
    Description

    Restrict results to specific employees using the same filter syntax as the Generic Reporting API, e.g. filter=employee_ids=508d5250-7399-4b65-a574-3da53d9ddc25. Multiple filters can be combined with | in a single filter parameter.

  • Name
    order
    Type
    string
    Description

    Sort by: checkin, checkout, or break_duration. Prefix a field with - for descending order, and combine multiple fields with |, e.g. order=-checkin|break_duration.

  • Name
    limit
    Type
    integer
    Description

    Number of results per page. Defaults to 100, maximum 1000.

  • Name
    offset
    Type
    integer
    Description

    Number of results to skip for pagination. Defaults to 0.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/workdays/?daterange=2024-06-01|2024-06-30" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 22,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
      "created_at": "2024-06-03T08:01:00",
      "modified_at": "2024-06-03T17:02:00",
      "workmonth_id": "a7b8c9d0-e1f2-3456-abcd-789012345678",
      "checkin": "2024-06-03T08:00:00",
      "checkout": "2024-06-03T17:00:00",
      "work_duration": 29700,
      "break_duration": 2700,
      "note": "",
      "short_break_policy": "enabled_15min"
    }
  ]
}
GET/api/v2/timestamps/workdays/:id/

Retrieve a Workday

Get details of a specific workday.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/workdays/f6a7b8c9-d0e1-2345-fabc-678901234567/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
POST/api/v2/timestamps/workdays/

Create a Workday

Create a new workday within a workmonth. This also creates the underlying timestamps and timespan for the workday. The day is validated against the workmonth: if the day does not exist in that month, the request fails with a 400 validation error. If checkout_time is earlier than checkin_time, the check-out is treated as an overnight shift and rolled over to the next day. On success, the full workday object is returned with status 200.

  • Name
    workmonth_id
    Type
    string (UUID)
    Description

    The workmonth to create the workday in. Required.

  • Name
    day
    Type
    integer
    Description

    The day of the month (1-31). Required.

  • Name
    checkin_time
    Type
    string (HH:MM:SS)
    Description

    The check-in time. Required.

  • Name
    checkout_time
    Type
    string (HH:MM:SS)
    Description

    The check-out time.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/workdays/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "workmonth_id": "a7b8c9d0-e1f2-3456-abcd-789012345678",
    "day": 15,
    "checkin_time": "08:00:00",
    "checkout_time": "17:00:00"
  }'

Response

{
  "id": "b3c4d5e6-f7a8-4901-bcde-234567890123",
  "created_at": "2024-06-20T09:15:00",
  "modified_at": "2024-06-20T09:15:00",
  "workmonth_id": "a7b8c9d0-e1f2-3456-abcd-789012345678",
  "checkin": "2024-06-15T08:00:00",
  "checkout": "2024-06-15T17:00:00",
  "work_duration": 29700,
  "break_duration": 2700,
  "note": null,
  "short_break_policy": "enabled_15min"
}
PATCH/api/v2/timestamps/workdays/:id/

Update a Workday

Update a workday's note field. note is the only writable field. PUT requests to the same path are also accepted and behave identically.

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/timestamps/workdays/f6a7b8c9-d0e1-2345-fabc-678901234567/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "Early departure approved"
  }'
DELETE/api/v2/timestamps/workdays/:id/

Delete a Workday

Delete a workday and all its associated timespans.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/timestamps/workdays/f6a7b8c9-d0e1-2345-fabc-678901234567/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
GET/api/v2/timestamps/workdays/export/csv/

Export as CSV

Export workday data as a CSV file. The response is a text/csv attachment. The same query parameters as the list endpoint (daterange, ids, token, filter) apply.

The export style is not selectable per request: it is determined by the institution-level setting export:monthly_csv_report, which must be one of workdays, timespans, or workmonths. If the setting holds any other value, the request fails with a 400 validation error.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/workdays/export/csv/?daterange=2024-06-01|2024-06-30" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Was this page helpful?