Timespans

A timespan represents a single working period defined by a check-in and check-out timestamp. Timespans belong to workdays and can have projects and tag assignments associated with them.

The Timespan Object

The default response includes a compact set of fields. Use ?verbosity=detail to receive the full object, which additionally contains workday_id, employee_id, the nested checkin/checkout timestamp objects, duration (in seconds), and additional_fields.

Name
id
Type
string (UUID)
Description
Unique identifier for the timespan.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp when the timespan was created.
Name
modified_at
Type
string (ISO 8601)
Description
Timestamp when the timespan was last modified.
Name
checkin_time
Type
string (ISO 8601)
Description
The check-in time.
Name
checkout_time
Type
string (ISO 8601) or null
Description
The check-out time, or null if currently working.
Name
project_id
Type
string (UUID) or null
Description
The assigned project ID.
Name
employee_comment
Type
string or null
Description
A comment left by the employee.
Name
tag_assignments
Type
array
Description
List of project tag assignments. Each entry contains tag_id, type (relative or absolute), and value.

GET/api/v2/timestamps/timespans/

List all Timespans

Retrieve a paginated list of timespans. Results are paginated with limit and offset (default limit 100, maximum 1000).

Query Parameters

Name
daterange
Type
string
Description
Return timespans that started within the range YYYY-MM-DD|YYYY-MM-DD. Either side may be left empty, e.g. ?daterange=|2024-06-30 or ?daterange=2024-06-01|.
Name
datetime_from
Type
string (ISO 8601)
Description
Return timespans whose check-in or check-out is at or after this datetime.
Name
datetime_to
Type
string (ISO 8601)
Description
Return timespans whose check-in or check-out is at or before this datetime.
Name
ids
Type
string
Description
Filter by timespan IDs, pipe-separated.
Name
employee_ids
Type
string
Description
Filter by employee IDs, pipe-separated.
Name
workmonth_ids
Type
string
Description
Filter by workmonth IDs, pipe-separated.
Name
workday_ids
Type
string
Description
Filter by workday IDs, pipe-separated.
Name
has_employee_comment
Type
string
Description
Set to true to return only timespans with an employee comment, or false for only timespans without one.
Name
employee_comment
Type
string
Description
Return timespans whose employee comment contains the given text (case-insensitive).
Name
order
Type
string
Description
Sort by: checkin_time, checkout_time, break_duration, or work_duration. Prefix with - for descending order. Multiple fields can be combined pipe-separated.
Name
verbosity
Type
string
Description
Response detail level: detail, duration, or device.

Request

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

Response

{
  "count": 42,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
      "created_at": "2024-06-03T08:00:12",
      "modified_at": "2024-06-03T17:00:05",
      "project_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "employee_comment": null,
      "tag_assignments": [
        {
          "tag_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
          "type": "relative",
          "value": "100"
        }
      ],
      "checkin_time": "2024-06-03T08:00:00",
      "checkout_time": "2024-06-03T17:00:00"
    }
  ]
}

GET/api/v2/timestamps/timespans/:id/

Retrieve a Timespan

Get details of a specific timespan. With ?verbosity=detail the response includes the workday and employee references, the nested check-in/check-out timestamps, and the duration in seconds.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/timespans/e5f6a7b8-c9d0-1234-efab-567890123456/?verbosity=detail" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
  "created_at": "2024-06-03T08:00:12",
  "modified_at": "2024-06-03T17:00:05",
  "workday_id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
  "project_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "employee_id": "3c4d5e6f-7a8b-9012-cdef-123456789012",
  "employee_comment": null,
  "checkin": {
    "id": "4d5e6f7a-8b9c-0123-def1-234567890123",
    "created_at": "2024-06-03T08:00:12",
    "modified_at": "2024-06-03T08:00:12",
    "time": "2024-06-03T08:00:00",
    "device_id": null,
    "device_serial_number": null,
    "creator": "online",
    "note": null,
    "identifier": null,
    "meta": null
  },
  "checkin_time": "2024-06-03T08:00:00",
  "checkout": {
    "id": "5e6f7a8b-9c0d-1234-ef12-345678901234",
    "created_at": "2024-06-03T17:00:05",
    "modified_at": "2024-06-03T17:00:05",
    "time": "2024-06-03T17:00:00",
    "device_id": null,
    "device_serial_number": null,
    "creator": "online",
    "note": null,
    "identifier": null,
    "meta": null
  },
  "checkout_time": "2024-06-03T17:00:00",
  "duration": 32400,
  "additional_fields": {},
  "tag_assignments": [
    {
      "tag_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "type": "relative",
      "value": "100"
    }
  ]
}

PATCH/api/v2/timestamps/timespans/:id/set-times/

Set Times

Modify the check-in and check-out times of an existing timespan. The response contains the updated timespan object.

Name
checkin
Type
string (ISO 8601)
Description
New check-in time. Required.
Name
checkout
Type
string (ISO 8601)
Description
New check-out time. Optional, but like the project assignment it is always overwritten: if you omit checkout, an existing check-out is deleted and the timespan becomes open. Include the current check-out time if you want to keep it.
Name
project_id
Type
string (UUID) or null
Description
Project to assign to the timespan. Optional, but see the note below.
Name
tag_assignments
Type
array
Description
Replacement tag assignments. Each entry contains tag_id, type (relative or absolute), and value. If omitted, existing tag assignments are kept.
Name
additional_fields
Type
object
Description
Custom additional fields. If omitted, the existing values are kept.

The project assignment is always overwritten by this endpoint: if you omit project_id (or send null), any project currently assigned to the timespan is removed. Include the current project_id in the request if you want to keep it.

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/timestamps/timespans/e5f6a7b8-c9d0-1234-efab-567890123456/set-times/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "checkin": "2024-06-03T08:30:00",
    "checkout": "2024-06-03T17:30:00",
    "project_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
  }'

POST/api/v2/timestamps/timespans/add-times/

Add Times

Add a new timespan to an existing workday. The response contains the created timespan object.

Name
workday_id
Type
string (UUID)
Description
The workday to add the timespan to. Required.
Name
checkin
Type
string (ISO 8601)
Description
Check-in time. Required.
Name
checkout
Type
string (ISO 8601)
Description
Check-out time. Optional.
Name
project_id
Type
string (UUID) or null
Description
Project to assign to the new timespan. Optional.
Name
tag_assignments
Type
array
Description
Tag assignments for the new timespan. Each entry contains tag_id, type (relative or absolute), and value. Optional.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/timespans/add-times/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "workday_id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
    "checkin": "2024-06-03T13:00:00",
    "checkout": "2024-06-03T17:00:00"
  }'

POST/api/v2/timestamps/timespans/:id/assign-project/

Assign a Project

Assign a project to a timespan by either project code or project ID. Provide exactly one of project_code or project_id — sending both results in a validation error. Assigning a project replaces all existing tag assignments on the timespan with a single relative assignment of 100% for that project.

Sending an empty body clears all tag assignments from the timespan. Note that this endpoint only manages tag assignments; the timespan's project_id field is not modified — use Set Times to change project_id.

Name
project_code
Type
string
Description
The project code (max 8 characters).
Name
project_id
Type
string (UUID)
Description
The project UUID.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/timespans/e5f6a7b8-c9d0-1234-efab-567890123456/assign-project/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_code": "P-101"
  }'

POST/api/v2/timestamps/timespans/:id/update-tag-assignments/

Update Tag Assignments

Replace all tag assignments on a timespan.

Name
tag_assignments
Type
array
Description
Array of tag assignment objects. Each object contains tag_id (project UUID), type (relative or absolute), and value (number). For relative assignments, value must be between 0 and 100.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/timespans/e5f6a7b8-c9d0-1234-efab-567890123456/update-tag-assignments/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_assignments": [
      {
        "tag_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
        "type": "relative",
        "value": 60
      },
      {
        "tag_id": "2b3c4d5e-6f7a-8901-bcde-f12345678901",
        "type": "relative",
        "value": 40
      }
    ]
  }'

POST/api/v2/timestamps/timespans/:id/update-employee-comment/

Update Employee Comment

Add or update the employee comment on a timespan.

Name
employee_comment
Type
string
Description
The comment text. Send an empty string to clear the comment.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/timespans/e5f6a7b8-c9d0-1234-efab-567890123456/update-employee-comment/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_comment": "Worked on client project documentation"
  }'

POST/api/v2/timestamps/timespans/modify-consecutive-timespans/

Modify Consecutive Timespans

Replace a set of consecutive timespans within the same workday with new timespans. This is useful for splitting or merging time entries.

The following rules apply:

All source timespans must be closed (have both a check-in and a check-out) and belong to the same workday.
The source timespans must be strictly consecutive: each timespan's check-out must equal the next timespan's check-in.
The new timespans must also be strictly consecutive, and they must cover exactly the same overall range as the source timespans: the first check-in and the last check-out must be identical to those of the source timespans.

The response is an array of the resulting timespan objects in detail verbosity.

Name
source_timespan_ids
Type
array of UUIDs
Description
The IDs of consecutive timespans to replace. Must belong to the same workday. Required.
Name
new_timespans
Type
array
Description
The replacement timespans. Each must have checkin and checkout timestamps, and optionally project_id and employee_comment.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/timestamps/timespans/modify-consecutive-timespans/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "source_timespan_ids": [
      "e5f6a7b8-c9d0-1234-efab-567890123456"
    ],
    "new_timespans": [
      {
        "checkin": "2024-06-03T08:00:00",
        "checkout": "2024-06-03T12:00:00",
        "project_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
      },
      {
        "checkin": "2024-06-03T12:00:00",
        "checkout": "2024-06-03T17:00:00",
        "project_id": "2b3c4d5e-6f7a-8901-bcde-f12345678901"
      }
    ]
  }'

Response

[
  {
    "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "created_at": "2024-06-03T08:00:12",
    "modified_at": "2024-06-04T09:15:00",
    "workday_id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
    "project_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "employee_id": "3c4d5e6f-7a8b-9012-cdef-123456789012",
    "employee_comment": null,
    "checkin": {
      "id": "4d5e6f7a-8b9c-0123-def1-234567890123",
      "created_at": "2024-06-03T08:00:12",
      "modified_at": "2024-06-03T08:00:12",
      "time": "2024-06-03T08:00:00",
      "device_id": null,
      "device_serial_number": null,
      "creator": "online",
      "note": null,
      "identifier": null,
      "meta": null
    },
    "checkin_time": "2024-06-03T08:00:00",
    "checkout": {
      "id": "6f7a8b9c-0d1e-2345-f123-456789012345",
      "created_at": "2024-06-04T09:15:00",
      "modified_at": "2024-06-04T09:15:00",
      "time": "2024-06-03T12:00:00",
      "device_id": null,
      "device_serial_number": null,
      "creator": "online",
      "note": "Projektzuweisung",
      "identifier": null,
      "meta": null
    },
    "checkout_time": "2024-06-03T12:00:00",
    "duration": 14400,
    "additional_fields": {},
    "tag_assignments": []
  },
  {
    "id": "7a8b9c0d-1e2f-3456-1234-567890123456",
    "created_at": "2024-06-04T09:15:00",
    "modified_at": "2024-06-04T09:15:00",
    "workday_id": "f6a7b8c9-d0e1-2345-fabc-678901234567",
    "project_id": "2b3c4d5e-6f7a-8901-bcde-f12345678901",
    "employee_id": "3c4d5e6f-7a8b-9012-cdef-123456789012",
    "employee_comment": null,
    "checkin": {
      "id": "8b9c0d1e-2f3a-4567-2345-678901234567",
      "created_at": "2024-06-04T09:15:00",
      "modified_at": "2024-06-04T09:15:00",
      "time": "2024-06-03T12:00:00",
      "device_id": null,
      "device_serial_number": null,
      "creator": "online",
      "note": "Projektzuweisung",
      "identifier": null,
      "meta": null
    },
    "checkin_time": "2024-06-03T12:00:00",
    "checkout": {
      "id": "5e6f7a8b-9c0d-1234-ef12-345678901234",
      "created_at": "2024-06-03T17:00:05",
      "modified_at": "2024-06-03T17:00:05",
      "time": "2024-06-03T17:00:00",
      "device_id": null,
      "device_serial_number": null,
      "creator": "online",
      "note": null,
      "identifier": null,
      "meta": null
    },
    "checkout_time": "2024-06-03T17:00:00",
    "duration": 18000,
    "additional_fields": {},
    "tag_assignments": []
  }
]

GET/api/v2/timestamps/timespans/:id/history/

View History

View the modification history of a timespan, showing who changed it and when. Each entry contains the previous check-in and check-out times, a change_reason, and a dump with a JSON snapshot of the timespan state at the time of the change (or null). The originator is the name of the user who made the change, or "System" for automated changes.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/timestamps/timespans/e5f6a7b8-c9d0-1234-efab-567890123456/history/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "9c0d1e2f-3a4b-5678-3456-789012345678",
      "created_at": "2024-06-04T10:00:00",
      "originator": "Admin User",
      "dump": null,
      "previous_checkin": "2024-06-03T08:00:00",
      "previous_checkout": "2024-06-03T17:00:00",
      "change_reason": "Corrected check-in time"
    }
  ]
}

DELETE/api/v2/timestamps/timespans/:id/

Delete a Timespan

Delete a timespan. This action cannot be undone. On success the API returns 204 No Content.

If the deleted timespan was the last one of its workday, the workday itself is deleted as well. Otherwise, the workday's breaks are recomputed.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/timestamps/timespans/e5f6a7b8-c9d0-1234-efab-567890123456/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"