Employee Groups

Employee groups let you organize employees into logical units such as departments, teams, or locations. Groups can be used to filter employees, restrict project access, and scope reports.

If your API token is restricted to specific permissions, it needs the matching scope for each operation: employee_groups:view for GET requests, employee_groups:add for POST, employee_groups:edit for PATCH/PUT, and employee_groups:delete for DELETE. Requests without the required permission return 403 Forbidden.

The Employee Group Object

Name
id
Type
string (UUID)
Description
Unique identifier for the group.
Name
name
Type
string
Description
The group name. Must be unique within your organization. Maximum length 256 characters.
Name
employee_count
Type
integer
Description
Number of active (non-archived) employees in this group. Read-only.

GET/api/v2/employees/groups/

List all Groups

Retrieve a list of all employee groups.

Query Parameters

Name
q
Type
string
Description
Search by group name.
Name
ids
Type
string
Description
Filter by group IDs (UUIDs), pipe-separated. Invalid UUIDs are ignored.
Name
modified_at__gte
Type
string (ISO 8601)
Description
Return only groups modified at or after this timestamp.

Results are scoped to the authenticated user: administrators see all groups of the organization, managers see only the groups they are assigned to, and employees see only their own group. For employee-role users, list and retrieve responses contain only the id and name fields.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/employees/groups/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Engineering",
      "employee_count": 12
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Sales",
      "employee_count": 8
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "name": "Operations",
      "employee_count": 5
    }
  ]
}

GET/api/v2/employees/groups/:id/

Retrieve a Group

Get details of a specific employee group.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/employees/groups/b2c3d4e5-f6a7-8901-bcde-f12345678901/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

POST/api/v2/employees/groups/

Create a Group

Create a new employee group. If the name is already used by another group in your organization, the API returns a 400 Bad Request validation error on the name field.

Name
name
Type
string
Description
The group name. Must be unique within your organization. Maximum length 256 characters. Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/groups/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marketing"
  }'

PATCH/api/v2/employees/groups/:id/

Update a Group

Rename an existing employee group. PUT requests to the same URL are also accepted; since name is the only writable field, both methods behave identically. As with create, a duplicate name returns a 400 Bad Request validation error on the name field.

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/employees/groups/b2c3d4e5-f6a7-8901-bcde-f12345678901/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Engineering"
  }'

DELETE/api/v2/employees/groups/:id/

Delete a Group

Delete an employee group. Employees in this group will become ungrouped.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/employees/groups/b2c3d4e5-f6a7-8901-bcde-f12345678901/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"