Time Tracking

Track working time by creating check-in and check-out events. This page covers the app-based timestamp API, which is the primary method for programmatic time tracking. For managing existing time records, see the Timespans, Workdays, and Workmonths endpoints.

Overview

There are two ways to track time via the API:

1. App Timestamps (this page) - Create punch events with an intent-based API (checkin, checkout, or auto). This is the recommended approach for integrating external time clocks or apps.
2. Employee Check-in/Check-out - Use the Employees endpoint to check employees in and out by their ID.

The App Timestamp Object

An app timestamp records a single punch event. It is returned by the create, list, and retrieve endpoints.

Create an App Timestamp

Create a punch event for an employee. Use intent: checkin to start a working session, intent: checkout to end it, or intent: auto to let the server decide: if the employee has an open timespan they are checked out, otherwise they are checked in.

curl -X POST "https://api.zeitstrom.com/api/v2/devices/app-timestamps/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "checkin",
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "time": "2024-06-20T08:00:00",
    "id": "clock-7-punch-000123",
    "project_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890"
  }'

curl -X POST "https://api.zeitstrom.com/api/v2/devices/app-timestamps/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "checkout",
    "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "time_utc": "2024-06-20T15:00:00",
    "id": "clock-7-punch-000124",
    "employee_comment": "Left early for a doctor appointment"
  }'

{
  "id": "b7d2f8a1-4c6e-4b2a-9f3d-2e5a8c1b7d90",
  "created_at": "2024-06-20T08:00:03",
  "timestamp_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "device_id": null,
  "intent": "checkin",
  "time": "2024-06-20T08:00:00",
  "error": null,
  "meta": null,
  "project_id": null,
  "tag_assignments": [],
  "employee_comment": null
}

{
  "id": "c8e3a9b2-5d7f-4c3b-8a4e-3f6b9d2c8ea1",
  "created_at": "2024-06-21T17:00:02",
  "timestamp_id": null,
  "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "device_id": null,
  "intent": "checkout",
  "time": "2024-06-21T17:00:00",
  "error": {
    "detail": "Error when adding checkout timestamp. No open timespan exists."
  },
  "meta": null,
  "project_id": null,
  "tag_assignments": [],
  "employee_comment": null
}

Retries and Idempotency

Create requests may be retried safely. A request is treated as a duplicate and does not create a second punch when one of the following matches an existing record:

1. The client-supplied id (recommended — generate a stable id per punch, at most 64 characters).
2. A local_id key inside meta, if no id was sent.
3. The combination of employee_id, time, and intent, if neither of the above was sent.

For a duplicate, the endpoint responds with 201 Created and returns the existing record instead of creating a new one. The tag assignments of the existing punch (and its timespan) are replaced with the values in the request — retrying without the original project_id or tag_assignments removes existing project assignments, so always retry with the exact same request body.

Unknown Employees

If employee_id does not match an employee of the authenticated caller's institution, the request is rejected with 400 Bad Request and nothing is stored. The error is reported under the employee_id key:

{
  "employee_id": [
    "Object with uid=a1b2c3d4-e5f6-7890-abcd-ef1234567890 does not exist."
  ]
}

Artemis terminals are the exception. They sync an offline queue and retry a rejected punch indefinitely, so a punch referencing an employee that no longer exists on the server would block the queue forever. For requests authenticated as a device whose model starts with Artemis, this one case is therefore acknowledged with 200 OK so the terminal can discard the punch. The body carries the same error detail as the 400 above, and nothing is stored — no app timestamp is created and no working time is booked.

List all App Timestamps

Retrieve a paginated list of punch events. Use this to read back submitted punches, for example to reconcile an external time clock.

Query Parameters

curl -X GET "https://api.zeitstrom.com/api/v2/devices/app-timestamps/?limit=100" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "b7d2f8a1-4c6e-4b2a-9f3d-2e5a8c1b7d90",
      "created_at": "2024-06-20T08:00:03",
      "timestamp_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
      "employee_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "device_id": null,
      "intent": "checkin",
      "time": "2024-06-20T08:00:00",
      "error": null,
      "meta": null,
      "project_id": null,
      "tag_assignments": [],
      "employee_comment": null
    }
  ]
}

Retrieve an App Timestamp

Get details of a specific punch event by its server-generated UUID.

curl -X GET "https://api.zeitstrom.com/api/v2/devices/app-timestamps/b7d2f8a1-4c6e-4b2a-9f3d-2e5a8c1b7d90/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"