Projects

Projects allow employees to track time against specific tasks, clients, or cost centers. Each project has a unique code that can be used for quick assignment on devices or via the API. Projects can be organized into categories and assigned to specific employee groups.

Each endpoint requires the corresponding API token permission: projects:view, projects:add, projects:edit, projects:archive, or projects:unarchive.

The Project Object

Name
id
Type
string (UUID)
Description
Unique identifier for the project.
Name
archived_at
Type
string (ISO 8601) or null
Description
Timestamp when the project was archived, or null if active.
Name
name
Type
string
Description
The project name. Required.
Name
code
Type
string
Description
A short code for the project (used on devices and for quick assignment). Required. Must be unique within your institution — a duplicate code is rejected with a validation error on the code field ("Der Code existiert bereits.").
Name
color
Type
string
Description
Display color as a 6-character hex code without the # prefix, e.g. "2196F3".
Name
category_id
Type
string (UUID) or null
Description
The project category ID.
Name
category_name
Type
string or null
Description
The category name. Read-only.
Name
group_assignments
Type
array of strings (UUID)
Description
IDs of the employee groups that have access to this project. Writable — see the note on assignments under Create a Project.
Name
device_assignments
Type
array of strings (UUID)
Description
UIDs of the devices this project is assigned to. Writable — see the note on assignments under Create a Project.
Name
locations
Type
array
Description
GPS locations associated with the project, each with latitude, longitude, max_distance (integer, in meters), and address. Writable, except for address, which is read-only and derived automatically from the coordinates.
Name
timebased_rules
Type
array or null
Description
Weekly time windows during which the project can be booked, or null for no restriction. An array of exactly 7 entries (Monday through Sunday), each a list of ["HH:MM", "HH:MM"] start/end pairs.
Name
interval_based_rules
Type
array or null
Description
Duration-based booking rules, or null for no restriction. Each rule is an object with reference ("workday" or "timespan"), min_working_time, and max_working_time.
Name
value_type
Type
string
Description
How the project value is interpreted: "relative" (default) or "absolute".
Name
value
Type
string (decimal)
Description
The configured value as a decimal string. Defaults to "100.00000".
Name
value_employee_configurable
Type
boolean
Description
Whether employees may adjust the value themselves. Defaults to false.
Name
additional_fields
Type
object
Description
Values for the custom project fields defined by your institution.

GET/api/v2/projects/projects/

List all Projects

Retrieve a paginated list of projects.

Query Parameters

Name
q
Type
string
Description
Search by project name or code.
Name
codes
Type
string
Description
Filter by project codes, pipe-separated.
Name
ids
Type
string
Description
Filter by project IDs, pipe-separated.
Name
group_ids
Type
string
Description
Filter by assigned employee group IDs, pipe-separated.
Name
category_ids
Type
string
Description
Filter by category IDs, pipe-separated.
Name
archived
Type
string
Description
Filter by archive status: true, false (default), or all.
Name
recent
Type
integer
Description
Return only projects the calling employee booked time on within the last N days (defaults to 30 if the value is not a valid integer). This filter only applies to employee-authenticated requests — it has no effect when authenticating with an API token.
Name
for-employee
Type
string (UUID)
Description
Filter projects accessible to a specific employee.
Name
modified_at__gte
Type
string (ISO 8601)
Description
Return only projects modified after this timestamp.
Name
limit
Type
integer
Description
Maximum number of results per page. Defaults to 100, maximum 1000.
Name
offset
Type
integer
Description
Number of results to skip for pagination.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/projects/projects/?q=website&archived=false" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "archived_at": null,
      "name": "Website Redesign",
      "code": "WEB-01",
      "color": "2196F3",
      "category_id": "c1c1c1c1-c2c2-c3c3-c4c4-c5c5c5c5c5c5",
      "category_name": "Development",
      "group_assignments": ["7f8e9d0c-1b2a-3c4d-5e6f-708192a3b4c5"],
      "device_assignments": [],
      "locations": [],
      "timebased_rules": null,
      "interval_based_rules": null,
      "value_type": "relative",
      "value": "100.00000",
      "value_employee_configurable": false,
      "additional_fields": {}
    }
  ]
}

GET/api/v2/projects/projects/:id/

Retrieve a Project

Get details of a specific project.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/projects/projects/1a2b3c4d-5e6f-7890-abcd-ef1234567890/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

POST/api/v2/projects/projects/

Create a Project

Create a new project.

Name
name
Type
string
Description
The project name. Required.
Name
code
Type
string
Description
A short code, unique within your institution. Required.
Name
color
Type
string
Description
Display color as a 6-character hex code without the # prefix, e.g. "4CAF50". Required.
Name
category_id
Type
string (UUID)
Description
Assign to a project category.
Name
locations
Type
array
Description
GPS locations for the project, each an object with latitude, longitude, and max_distance (integer, in meters). The address of each location is computed automatically from the coordinates and cannot be set.
Name
group_assignments
Type
array of strings (UUID)
Description
IDs of the employee groups that should have access to this project.
Name
device_assignments
Type
array of strings (UUID)
Description
UIDs of the devices this project should be assigned to.

The remaining project object fields — timebased_rules, interval_based_rules, value_type, value, value_employee_configurable, and additional_fields — can also be set on create and update.

Changes to group_assignments and device_assignments are only applied when the payload also contains a locations key. Include "locations": [] (or the project's current locations) whenever you send assignments.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/projects/projects/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App Development",
    "code": "MOB-01",
    "color": "4CAF50",
    "category_id": "c1c1c1c1-c2c2-c3c3-c4c4-c5c5c5c5c5c5",
    "locations": [],
    "group_assignments": ["7f8e9d0c-1b2a-3c4d-5e6f-708192a3b4c5"]
  }'

PUT/api/v2/projects/projects/:id/

Update a Project

Update an existing project. PUT replaces the project and requires all required fields; PATCH is also supported for partial updates and only changes the fields you send.

Request

curl -X PUT "https://api.zeitstrom.com/api/v2/projects/projects/1a2b3c4d-5e6f-7890-abcd-ef1234567890/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Redesign v2",
    "code": "WEB-02",
    "color": "1565C0"
  }'

POST/api/v2/projects/projects/:id/archive/

Archive a Project

Archive a project. Archived projects cannot be assigned to new timespans but historical data is preserved. The response contains the full project object with archived_at set. Archiving a project that is already archived returns a 400 validation error.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/projects/projects/1a2b3c4d-5e6f-7890-abcd-ef1234567890/archive/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

POST/api/v2/projects/projects/:id/unarchive/

Unarchive a Project

Restore a previously archived project. The response contains the full project object with archived_at set back to null. Unarchiving a project that is not archived returns a 400 validation error.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/projects/projects/1a2b3c4d-5e6f-7890-abcd-ef1234567890/unarchive/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"