Workmonths

A workmonth aggregates all workdays for a specific employee within a calendar month. It provides summary statistics including total work time, target work time, and incomplete day counts.

The Workmonth Object

  • Name
    id
    Type
    string (UUID)
    Description

    Unique identifier for the workmonth.

  • Name
    created_at
    Type
    string (ISO 8601)
    Description

    Timestamp when the workmonth was created.

  • Name
    modified_at
    Type
    string (ISO 8601)
    Description

    Timestamp when the workmonth was last modified.

  • Name
    employee_id
    Type
    string (UUID)
    Description

    The employee this workmonth belongs to. Read-only.

  • Name
    year
    Type
    integer
    Description

    The year (e.g. 2024).

  • Name
    month
    Type
    integer
    Description

    The month (1-12).

  • Name
    workday_count
    Type
    integer
    Description

    Number of workdays in this month. Read-only.

  • Name
    incomplete_days_count
    Type
    integer
    Description

    Number of days with missing check-outs. Read-only.

  • Name
    worktime_count
    Type
    integer
    Description

    Total working time in seconds. Read-only.

  • Name
    target_worktime
    Type
    integer
    Description

    Target working time in seconds based on the employee's contract. Read-only.

Detail Verbosity

When using ?verbosity=detail (available on the list and retrieve endpoints), the response includes three additional fields:

  • Name
    target_worktime_effective
    Type
    integer
    Description

    The effective monthly target in seconds, after subtracting public holidays and target-reducing absences. Read-only.

  • Name
    target_worktime_model
    Type
    string
    Description

    The employee's daily working times model: weekly, monthly, or season. Read-only.

  • Name
    calendar
    Type
    array
    Description

    One entry per calendar day of the month, with nested workdays and absences. Read-only.

With ?verbosity=detail, the meaning of target_worktime changes for employees on the monthly model: it carries the nominal monthly target (contracted hours per month × 3600), while target_worktime_effective carries the reduced, effective value. Without the verbosity parameter, target_worktime always contains the effective value. For the weekly and season models both values are identical.

Each calendar entry has the following structure:

  • Name
    day
    Type
    integer
    Description

    Day of the month (1-31).

  • Name
    isoformat
    Type
    string
    Description

    The date in YYYY-MM-DD format.

  • Name
    weekday
    Type
    string
    Description

    German weekday abbreviation: Mo, Di, Mi, Do, Fr, Sa, or So.

  • Name
    target_worktime
    Type
    integer
    Description

    Target working time for this day in seconds.

  • Name
    day_off_reasons
    Type
    array
    Description

    Reasons why the day is (partially) off, e.g. {"type": "no-work-day"} or {"type": "public-holiday", "name": "..."}. Absence days appear as {"type": "missing-day", "name": "..."}.

  • Name
    workdays
    Type
    array
    Description

    Workday records for this day, each with id, checkin, checkout, break_duration, work_duration, note, and history_change_count.

  • Name
    missing_days
    Type
    array
    Description

    Absence entries applicable to this day, each with id, missing_type (e.g. holiday, sickday), label, affected_hours, affected_hours_for_day, target_hour_behaviour (substract_from_target_hours or add_to_debit_hours), date_from, date_to, comment, and attachment. Absence entries only appear if your token also has the absence:view permission. For employees on the monthly model, synthetic public-holiday reduction entries with id: null appear regardless of that permission.

GET/api/v2/timestamps/workmonths/

List all Workmonths

Retrieve a paginated list of workmonths. Requires the workmonths:view permission.

Query Parameters

  • Name
    ids
    Type
    string
    Description

    Filter by workmonth IDs, pipe-separated.

  • Name
    employee_ids
    Type
    string
    Description

    Filter by employee IDs, pipe-separated.

  • Name
    years
    Type
    string
    Description

    Filter by years, pipe-separated (e.g. 2024|2025).

  • Name
    months
    Type
    string
    Description

    Filter by months, pipe-separated (e.g. 1|2|3).

  • Name
    incomplete_days
    Type
    boolean
    Description

    Filter by presence of incomplete days.

  • Name
    verbosity
    Type
    string
    Description

    Use detail for extended workmonth data including calendar.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/workmonths/?employee_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890&years=2024&months=6" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "a7b8c9d0-e1f2-3456-abcd-789012345678",
      "created_at": "2024-06-01T00:00:00",
      "modified_at": "2024-06-30T23:59:59",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "year": 2024,
      "month": 6,
      "workday_count": 20,
      "incomplete_days_count": 0,
      "worktime_count": 576000,
      "target_worktime": 576000
    }
  ]
}
GET/api/v2/timestamps/workmonths/:id/

Retrieve a Workmonth

Get details of a specific workmonth. Requires the workmonths:view permission. The example below uses ?verbosity=detail; the calendar array is abbreviated — the real response contains one entry per day of the month.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/workmonths/a7b8c9d0-e1f2-3456-abcd-789012345678/?verbosity=detail" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "a7b8c9d0-e1f2-3456-abcd-789012345678",
  "created_at": "2024-06-01T00:00:00",
  "modified_at": "2024-06-30T23:59:59",
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "year": 2024,
  "month": 6,
  "workday_count": 20,
  "incomplete_days_count": 0,
  "worktime_count": 576000,
  "target_worktime": 576000,
  "target_worktime_effective": 576000,
  "target_worktime_model": "weekly",
  "calendar": [
    {
      "day": 1,
      "target_worktime": 0,
      "isoformat": "2024-06-01",
      "day_off_reasons": [{ "type": "no-work-day" }],
      "weekday": "Sa",
      "workdays": [],
      "missing_days": []
    },
    {
      "day": 3,
      "target_worktime": 28800,
      "isoformat": "2024-06-03",
      "day_off_reasons": [],
      "weekday": "Mo",
      "workdays": [
        {
          "id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
          "checkin": "2024-06-03T08:00:00",
          "checkout": "2024-06-03T17:00:00",
          "break_duration": 2700,
          "work_duration": 29700,
          "note": "",
          "history_change_count": 0
        }
      ],
      "missing_days": []
    }
  ]
}
POST/api/v2/timestamps/workmonths/

Create a Workmonth

Create a new workmonth for an employee. This is typically done automatically, but can be triggered manually. Requires the workmonths:add permission.

A workmonth is unique per employee, year, and month — creating a duplicate returns a validation error "This month already exists." on the month field. The year must not be earlier than the year before your institution was created and not more than two years in the future.

  • Name
    employee_id
    Type
    string (UUID)
    Description

    The employee to create the workmonth for. Required.

  • Name
    year
    Type
    integer
    Description

    The year. Required.

  • Name
    month
    Type
    integer
    Description

    The month (1-12). Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/workmonths/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "year": 2024,
    "month": 7
  }'
GET/api/v2/timestamps/workmonths/:id/working-time-balance/

Working Time Balance

Get the working time credit and debit balance for a specific workmonth. Requires the workmonths:view permission.

The balance is computed as follows:

  • For past months, the totals for the whole month are returned. Exception: a workmonth created after its month had already ended returns 0 for both values.
  • For the current month, only days up to and including yesterday are counted.
  • The current day is included as well if it already has at least one complete timespan or an absence day.
  • Name
    worktime_count
    Type
    integer
    Description

    Accumulated working time (credit) in seconds.

  • Name
    target_worktime
    Type
    integer
    Description

    Accumulated target working time (debit) in seconds.

  • Name
    is_active_month
    Type
    boolean
    Description

    Whether the workmonth's period has not ended yet (true for the current and future months).

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/workmonths/a7b8c9d0-e1f2-3456-abcd-789012345678/working-time-balance/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "worktime_count": 576000,
  "target_worktime": 576000,
  "is_active_month": false
}
GET/api/v2/timestamps/workmonths/:id/download/

Download Report

Download the monthly report for a workmonth as a PDF document. Requires the workmonths:download-report permission. The report is generated on the fly and streamed as application/pdf (served with Content-Disposition: inline), so treat the response body as binary data — generation may take a few seconds.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/workmonths/a7b8c9d0-e1f2-3456-abcd-789012345678/download/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -o report-june-2024.pdf

Was this page helpful?