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, the response includes a calendar field with nested workday details including timespans and absences for each day.

GET/api/v2/timestamps/workmonths/

List all Workmonths

Retrieve a paginated list of workmonths.

Query Parameters

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,
  "results": [
    {
      "id": "a7b8c9d0-e1f2-3456-abcd-789012345678",
      "created_at": "2024-06-01T00:00:00Z",
      "modified_at": "2024-06-30T23:59:59Z",
      "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.

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>"

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.

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.

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>"

GET/api/v2/timestamps/workmonths/:id/download/

Download Report

Download the monthly report for a workmonth as a PDF document.

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