Working Time Transactions

Working time transactions allow manual adjustments to an employee's working time balance. Use them to record overtime corrections, initial balance carryovers, or other adjustments that cannot be captured through regular time tracking.

Endpoints on this page require an API token permission: working_time_transactions:view for listing, retrieving, and aggregating, working_time_transactions:add for creating, working_time_transactions:edit for updating, and working_time_transactions:delete for deleting. The transaction types endpoint only requires authentication.

The Working Time Transaction Object

Name
id
Type
string (UUID)
Description
Unique identifier for the transaction.
Name
type
Type
string
Description
Transaction type: auto, custom, or workmonth. Transactions of type workmonth are generated automatically by Zeitstrom. Read-only after creation.
Name
date
Type
string (ISO 8601 datetime)
Description
The effective date and time of the transaction, e.g. 2024-01-01T00:00:00. Read-only after creation.
Name
employee_id
Type
string (UUID)
Description
The employee this transaction belongs to. Read-only after creation.
Name
amount
Type
decimal
Description
The adjustment amount in hours. Positive values add time, negative values deduct. Returned as a decimal string with five decimal places, e.g. "4.00000".
Name
comment
Type
string
Description
A description of the adjustment.
Name
additional_fields
Type
object
Description
Custom key-value data.

GET/api/v2/timestamps/working-time-transactions/

List all Transactions

Retrieve a paginated list of working time transactions.

Query Parameters

Name
employee_ids
Type
string
Description
Filter by employee IDs, pipe-separated.
Name
employee_group_ids
Type
string
Description
Filter by employee group IDs, pipe-separated. Use null for ungrouped.
Name
date__gte
Type
string (ISO 8601 datetime)
Description
Filter by minimum date, e.g. 2024-01-01T00:00:00.
Name
date__lte
Type
string (ISO 8601 datetime)
Description
Filter by maximum date, e.g. 2024-01-31T23:59:59.
Name
types
Type
string
Description
Filter by type, pipe-separated for multiple values, e.g. types=auto|custom. Available types: auto, custom, workmonth.
Name
comments
Type
string
Description
Filter by exact comment text, pipe-separated for multiple values.
Name
order
Type
string
Description
Sort by date or -date (descending).
Name
limit
Type
integer
Description
Maximum number of results per page. Defaults to 100, maximum is 1000.
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/working-time-transactions/?employee_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890&date__gte=2024-01-01T00:00:00" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "w1w1w1w1-w2w2-w3w3-w4w4-w5w5w5w5w5w5",
      "type": "custom",
      "date": "2024-01-01T00:00:00",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "4.00000",
      "comment": "Overtime carryover from December 2023 (4 hours)",
      "additional_fields": {}
    }
  ]
}

GET/api/v2/timestamps/working-time-transactions/:id/

Retrieve a Transaction

Retrieve a single working time transaction by its ID.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/working-time-transactions/w1w1w1w1-w2w2-w3w3-w4w4-w5w5w5w5w5w5/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "w1w1w1w1-w2w2-w3w3-w4w4-w5w5w5w5w5w5",
  "type": "custom",
  "date": "2024-01-01T00:00:00",
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "amount": "4.00000",
  "comment": "Overtime carryover from December 2023 (4 hours)",
  "additional_fields": {}
}

POST/api/v2/timestamps/working-time-transactions/

Create a Transaction

Create a manual working time adjustment.

Name
employee_id
Type
string (UUID)
Description
The employee. Required.
Name
type
Type
string
Description
Transaction type. Normally only custom is allowed; auto additionally requires the working_time_transactions:assign-type-auto permission on your API token. Required.
Name
date
Type
string (ISO 8601 datetime)
Description
Effective date and time. Required.
Name
amount
Type
decimal
Description
Adjustment amount in hours. Positive values add time, negative values deduct. Required.
Name
comment
Type
string
Description
Description of the adjustment. Required.
Name
additional_fields
Type
object
Description
Custom key-value data.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/working-time-transactions/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "custom",
    "date": "2024-06-01T00:00:00",
    "amount": 2.0,
    "comment": "2 hours overtime compensation"
  }'

PUT/api/v2/timestamps/working-time-transactions/:id/

Update a Transaction

Update an existing working time transaction. Only amount, comment, and additional_fields can be changed — type, date, and employee_id are read-only and ignored if sent. Use PATCH instead of PUT for partial updates.

Only transactions of type custom and auto can be updated. Attempting to update an automatically generated workmonth transaction returns a validation error.

Request

curl -X PUT "https://api.zeitstrom.com/api/v2/timestamps/working-time-transactions/w1w1w1w1-w2w2-w3w3-w4w4-w5w5w5w5w5w5/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5.0,
    "comment": "Corrected overtime carryover (5 hours)"
  }'

DELETE/api/v2/timestamps/working-time-transactions/:id/

Delete a Transaction

Delete a working time transaction.

Only transactions of type custom and auto can be deleted. Attempting to delete an automatically generated workmonth transaction returns a validation error.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/timestamps/working-time-transactions/w1w1w1w1-w2w2-w3w3-w4w4-w5w5w5w5w5w5/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

GET/api/v2/timestamps/working-time-transactions/aggregate/

Aggregate

Get the summed working time balance in hours per employee. Accepts the same query parameters as the list endpoint, and the response is paginated.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/working-time-transactions/aggregate/?employee_ids=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "6.00000"
    }
  ]
}

GET/api/v2/timestamps/working-time-transactions/types/

Transaction Types

Get the list of available transaction types. Use ?q=<text> to search within the labels and ?ids=<id1>|<id2> to filter by specific type IDs. Labels are returned in German.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/working-time-transactions/types/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "workmonth",
      "label": "Arbeitsmonat"
    },
    {
      "id": "custom",
      "label": "Manueller Eintrag"
    },
    {
      "id": "auto",
      "label": "Automatisch"
    }
  ]
}