Managers

Managers are the user accounts that sign in to the Zeitstrom web application to administer your organization: administrators have full access, while managers only see the employee groups they are assigned to. This API lets you list, invite, update, and deactivate these accounts and control their employee-group assignments.

If your API token is restricted to specific permissions, it needs the matching scope for each operation: managers:view for GET requests, managers:add for POST, managers:edit for PUT/PATCH, and managers:delete for DELETE. Requests without the required permission return 403 Forbidden. Note that validation error messages returned by this endpoint may be localized in German.

The Manager Object

  • Name
    id
    Type
    string (UUID)
    Description

    Unique identifier for the account. Read-only.

  • Name
    created_at
    Type
    string (ISO 8601, local time)
    Description

    When the account was created. Read-only.

  • Name
    modified_at
    Type
    string (ISO 8601, local time)
    Description

    When the account was last modified. Read-only.

  • Name
    full_name
    Type
    string
    Description

    The person's full name. Maximum length 255 characters. Optional; defaults to an empty string.

  • Name
    email
    Type
    string
    Description

    The email address the person uses to sign in. The invitation email is sent to this address. Maximum length 255 characters. Required.

  • Name
    role
    Type
    string
    Description

    The account role: admin (full access to the organization) or manager (access limited to assigned employee groups). Must be included in every create and update request.

  • Name
    permission_set
    Type
    string or null
    Description

    Identifier of a custom permission set that further restricts what the account can do, in the format role$name (e.g. manager$Reporting). Available identifiers can be retrieved from the permission sets endpoint. Set to null to use the role's default permissions. Values that do not match a configured permission set for the account's role are ignored and the role's default permissions apply.

  • Name
    group_assignments
    Type
    array of strings (UUID)
    Description

    IDs of the employee groups the account is assigned to (see Employee Groups). A manager only sees employees in these groups. Required with at least one entry when role is manager. Administrators have access to all groups and should carry no group assignments; omit the field or pass an empty array for them.

GET/api/v2/accounts/managers/

List all Managers

Retrieve a paginated list of all active administrator and manager accounts of your organization, ordered by full name. Deactivated accounts are not included.

Query Parameters

  • Name
    q
    Type
    string
    Description

    Search by full name (case-insensitive substring match).

  • Name
    ids
    Type
    string
    Description

    Filter by account IDs (UUIDs), pipe-separated. Invalid UUIDs are ignored.

  • Name
    roles
    Type
    string
    Description

    Filter by role, pipe-separated: admin, manager, or admin|manager.

  • Name
    employee_groups
    Type
    string
    Description

    Filter by assigned employee groups, pipe-separated group IDs (UUIDs). Returns managers assigned to at least one of the given groups. Administrators always match this filter, since they have access to all groups.

  • Name
    limit
    Type
    integer
    Description

    Number of results per page. Defaults to 100, maximum 1000.

  • Name
    offset
    Type
    integer
    Description

    Number of results to skip for pagination. Defaults to 0.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/accounts/managers/?roles=admin|manager" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "a1f8c6d2-3e57-49b0-8f21-6c94d0e7b3a5",
      "created_at": "2023-11-02T08:12:45.301842",
      "modified_at": "2024-05-27T16:40:03.518203",
      "full_name": "Jonas Berger",
      "email": "jonas.berger@example.com",
      "role": "admin",
      "permission_set": null,
      "group_assignments": []
    },
    {
      "id": "7f3c9a2e-5b41-4d88-9c17-2e6a8b0d4f53",
      "created_at": "2024-03-11T09:24:37.518203",
      "modified_at": "2024-06-18T14:04:12.093481",
      "full_name": "Sabine Krüger",
      "email": "sabine.krueger@example.com",
      "role": "manager",
      "permission_set": "manager$Reporting",
      "group_assignments": [
        "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "c3d4e5f6-a7b8-9012-cdef-123456789012"
      ]
    }
  ]
}
GET/api/v2/accounts/managers/:id/

Retrieve a Manager

Get details of a specific manager or administrator account. Deactivated accounts return 404 Not Found.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/accounts/managers/7f3c9a2e-5b41-4d88-9c17-2e6a8b0d4f53/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "7f3c9a2e-5b41-4d88-9c17-2e6a8b0d4f53",
  "created_at": "2024-03-11T09:24:37.518203",
  "modified_at": "2024-06-18T14:04:12.093481",
  "full_name": "Sabine Krüger",
  "email": "sabine.krueger@example.com",
  "role": "manager",
  "permission_set": "manager$Reporting",
  "group_assignments": [
    "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "c3d4e5f6-a7b8-9012-cdef-123456789012"
  ]
}
POST/api/v2/accounts/managers/

Create a Manager

Invite a new manager or administrator. The account is activated immediately and an invitation email is sent to the given email address. The invitation contains a generated initial password and a sign-in link that is valid for seven days.

Requests with role set to manager must include group_assignments with at least one employee group ID. All listed group IDs must exist in your organization and each ID may appear only once; otherwise the request fails with a 400 validation error. For role set to admin, omit group_assignments or pass an empty array — administrators have access to all groups regardless of assignments. Note that unlike updates, group IDs sent in a create request are stored even for administrators, so do not include any.

On success, the API returns status 201 with the created object.

  • Name
    full_name
    Type
    string
    Description

    The person's full name. Maximum length 255 characters. Optional.

  • Name
    email
    Type
    string
    Description

    The email address the invitation is sent to, later used to sign in. Required.

  • Name
    role
    Type
    string
    Description

    admin or manager. Required.

  • Name
    permission_set
    Type
    string or null
    Description

    Identifier of a custom permission set (role$name), or null for the role's default permissions. Optional.

  • Name
    group_assignments
    Type
    array of strings (UUID)
    Description

    Employee group IDs to assign. Required with at least one entry when role is manager.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/accounts/managers/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Miriam Vogel",
    "email": "miriam.vogel@example.com",
    "role": "manager",
    "permission_set": null,
    "group_assignments": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]
  }'

Response

{
  "id": "3d8e51ba-9c07-4f26-b1e4-58a2f7c60d19",
  "created_at": "2024-06-24T10:31:08.442917",
  "modified_at": "2024-06-24T10:31:08.442951",
  "full_name": "Miriam Vogel",
  "email": "miriam.vogel@example.com",
  "role": "manager",
  "permission_set": null,
  "group_assignments": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]
}
PUT/api/v2/accounts/managers/:id/

Update a Manager

Update an existing account. PATCH requests to the same URL are also accepted, but role must be included in every update request regardless of the method — treat updates as full replacements of the fields you see on the object.

Group assignments are replaced as a whole: groups missing from group_assignments are unassigned, new ones are assigned. The same validation rules as for create apply — a manager needs at least one group, and when changing the role to admin, all group assignments are removed automatically. No email is sent for updates.

Request

curl -X PUT "https://api.zeitstrom.com/api/v2/accounts/managers/7f3c9a2e-5b41-4d88-9c17-2e6a8b0d4f53/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "full_name": "Sabine Krüger",
    "email": "sabine.krueger@example.com",
    "role": "manager",
    "permission_set": null,
    "group_assignments": ["c3d4e5f6-a7b8-9012-cdef-123456789012"]
  }'

Response

{
  "id": "7f3c9a2e-5b41-4d88-9c17-2e6a8b0d4f53",
  "created_at": "2024-03-11T09:24:37.518203",
  "modified_at": "2024-06-24T11:02:51.207364",
  "full_name": "Sabine Krüger",
  "email": "sabine.krueger@example.com",
  "role": "manager",
  "permission_set": null,
  "group_assignments": ["c3d4e5f6-a7b8-9012-cdef-123456789012"]
}
DELETE/api/v2/accounts/managers/:id/

Delete a Manager

Deactivate an account. This is a soft delete: the account is marked as inactive, can no longer sign in, and disappears from all list and retrieve responses, but its data is not removed. On success, the API returns status 204 with no content.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/accounts/managers/7f3c9a2e-5b41-4d88-9c17-2e6a8b0d4f53/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
GET/api/v2/accounts/managers/roles/

List Roles

Retrieve the roles that can be assigned via this API, as a paginated list of choices. Labels are human-readable display names in German. Supports the q parameter to search within labels and the ids parameter (pipe-separated) to filter by role identifier. This endpoint does not require a specific token permission.

Request

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

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "admin",
      "label": "Administrator"
    },
    {
      "id": "manager",
      "label": "Abteilungsleiter"
    }
  ]
}
GET/api/v2/accounts/managers/permission-sets/

List Permission Sets

Retrieve the custom permission sets configured for your organization, as a paginated list of choices. The id (in the format role$name) is the value to use for the permission_set field of an account. If no permission sets are configured, the result list is empty. Supports the q parameter to search within labels and the ids parameter (pipe-separated) to filter by identifier. Requires the managers:view permission.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/accounts/managers/permission-sets/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "manager$Reporting",
      "label": "Reporting"
    },
    {
      "id": "manager$Scheduling",
      "label": "Scheduling"
    }
  ]
}

Was this page helpful?