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 including nested check-in/check-out timestamps and workday references.

Name
id
Type
string (UUID)
Description
Unique identifier for the timespan.
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
Description
A comment left by the employee.
Name
tag_assignments
Type
array
Description
List of project tag assignments.

GET/api/v2/timestamps/timespans/

List all Timespans

Retrieve a paginated list of timespans.

Query Parameters

Name
daterange
Type
string
Description
Filter by date range: YYYY-MM-DD|YYYY-MM-DD.
Name
employee_ids
Type
string
Description
Filter by employee IDs, 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&verbosity=detail" \
  -H "Authorization: Token YOUR_API_TOKEN"

Response

{
  "count": 42,
  "results": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
      "checkin_time": "2024-06-03T08:00:00Z",
      "checkout_time": "2024-06-03T17:00:00Z"
    }
  ]
}

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

Retrieve a Timespan

Get details of a specific timespan.

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"

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

Set Times

Modify the check-in and check-out times of an existing timespan.

Name
checkin
Type
string (ISO 8601)
Description
New check-in time. Required.
Name
checkout
Type
string (ISO 8601)
Description
New check-out time. Optional.

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:00Z",
    "checkout": "2024-06-03T17:30:00Z"
  }'

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

Add Times

Add a new timespan to an existing workday.

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.

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:00Z",
    "checkout": "2024-06-03T17:00:00Z"
  }'

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

Assign a Project

Assign a project to a timespan by either project code or 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 with tag_id, type, and value.

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.

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:00Z",
        "checkout": "2024-06-03T12:00:00Z",
        "project_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
      },
      {
        "checkin": "2024-06-03T13:00:00Z",
        "checkout": "2024-06-03T17:00:00Z",
        "project_id": "2b3c4d5e-6f7a-8901-bcde-f12345678901"
      }
    ]
  }'

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

View History

View the modification history of a timespan, showing who changed it and when.

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,
  "results": [
    {
      "id": "h1h1h1h1-h2h2-h3h3-h4h4-h5h5h5h5h5h5",
      "created_at": "2024-06-04T10:00:00Z",
      "originator": "Admin User",
      "previous_checkin": "2024-06-03T08:00:00Z",
      "previous_checkout": "2024-06-03T17:00:00Z",
      "change_reason": "Corrected check-in time"
    }
  ]
}

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

Delete a Timespan

Delete a timespan. This action cannot be undone.

Request

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