Employees

Employees are the core resource in Zeitstrom. They represent the people in your organization whose working time is being tracked. You can create, update, archive, and manage check-ins and check-outs for employees.

The Employee Object

  • Name
    id
    Type
    string (UUID)
    Description

    Unique identifier for the employee.

  • Name
    created_at
    Type
    string (ISO 8601)
    Description

    Timestamp when the employee was created.

  • Name
    modified_at
    Type
    string (ISO 8601)
    Description

    Timestamp when the employee was last modified.

  • Name
    archived_at
    Type
    string (ISO 8601) or null
    Description

    Timestamp when the employee was archived, or null if active.

  • Name
    first_name
    Type
    string
    Description

    The employee's first name. Required.

  • Name
    last_name
    Type
    string
    Description

    The employee's last name. Required.

  • Name
    email
    Type
    string
    Description

    The employee's email address.

  • Name
    employee_group_id
    Type
    string (UUID) or null
    Description

    The ID of the employee group this employee belongs to.

  • Name
    employee_group_name
    Type
    string
    Description

    The name of the employee group. Read-only.

  • Name
    external_id
    Type
    string
    Description

    An external identifier for integration with third-party systems.

  • Name
    external_uid
    Type
    string
    Description

    An external unique identifier.

  • Name
    project_id
    Type
    string (UUID) or null
    Description

    Default project assigned to this employee.

  • Name
    accounting_number
    Type
    string
    Description

    The employee's accounting or personnel number.

  • Name
    hourly_rate
    Type
    decimal
    Description

    The employee's hourly rate.

  • Name
    is_male
    Type
    boolean
    Description

    Gender indicator.

  • Name
    physical_token_id
    Type
    string
    Description

    RFID card or physical token identifier.

  • Name
    terminal_pin
    Type
    string or null
    Description

    PIN code for terminal authentication.

  • Name
    additional_fields
    Type
    object
    Description

    Custom key-value data attached to the employee.

  • Name
    username
    Type
    string
    Description

    The associated user account username. Read-only.

  • Name
    can_be_deleted
    Type
    boolean
    Description

    Whether the employee can be permanently deleted. Read-only.

GET/api/v2/employees/employees/

List all Employees

Retrieve a paginated list of employees. By default, archived employees are excluded.

Query Parameters

  • Name
    q
    Type
    string
    Description

    Search by full name or token number.

  • Name
    employee_groups
    Type
    string
    Description

    Filter by employee group IDs, pipe-separated. Use null for ungrouped employees.

  • Name
    archived
    Type
    string
    Description

    Filter by archive status: true, false (default), or all.

  • Name
    external_uids
    Type
    string
    Description

    Filter by external UIDs, pipe-separated.

  • Name
    token
    Type
    string
    Description

    Filter by RFID token, pipe-separated.

  • Name
    terminal_pins
    Type
    string
    Description

    Filter by terminal PINs, pipe-separated.

  • Name
    modified_at__gte
    Type
    string (ISO 8601)
    Description

    Return only employees modified after this timestamp.

  • Name
    verbosity
    Type
    string
    Description

    Response detail level: device, minimal, absence, or detail.

Request

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

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "created_at": "2024-01-15T08:30:00Z",
      "modified_at": "2024-06-20T14:22:00Z",
      "archived_at": null,
      "first_name": "Max",
      "last_name": "Mustermann",
      "email": "max@example.com",
      "employee_group_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "employee_group_name": "Engineering",
      "external_id": "EMP-001",
      "accounting_number": "1001",
      "hourly_rate": "25.00",
      "is_male": true,
      "physical_token_id": "04A3B2C1D0",
      "terminal_pin": "1234",
      "additional_fields": {}
    }
  ]
}
GET/api/v2/employees/employees/:id/

Retrieve an Employee

Get details of a specific employee by their UUID.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
POST/api/v2/employees/employees/

Create an Employee

Create a new employee in your organization.

Required Parameters

  • Name
    first_name
    Type
    string
    Description

    The employee's first name.

  • Name
    last_name
    Type
    string
    Description

    The employee's last name.

Optional Parameters

  • Name
    email
    Type
    string
    Description

    Email address.

  • Name
    employee_group_id
    Type
    string (UUID)
    Description

    Assign to an employee group.

  • Name
    external_id
    Type
    string
    Description

    External identifier for third-party integration.

  • Name
    accounting_number
    Type
    string
    Description

    Personnel or accounting number.

  • Name
    hourly_rate
    Type
    decimal
    Description

    Hourly rate.

  • Name
    physical_token_id
    Type
    string
    Description

    RFID card identifier.

  • Name
    terminal_pin
    Type
    string
    Description

    PIN code for terminal access.

  • Name
    project_id
    Type
    string (UUID)
    Description

    Default project assignment.

  • Name
    additional_fields
    Type
    object
    Description

    Custom key-value data.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Erika",
    "last_name": "Mustermann",
    "email": "erika@example.com",
    "employee_group_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "accounting_number": "1002"
  }'
PATCH/api/v2/employees/employees/:id/

Update an Employee

Update an existing employee. Only the fields you include in the request body will be changed.

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "max.mustermann@newdomain.com",
    "hourly_rate": "30.00"
  }'
DELETE/api/v2/employees/employees/:id/

Delete an Employee

Permanently delete an employee. This is only possible if can_be_deleted is true. For most cases, use archiving instead.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
POST/api/v2/employees/employees/:id/archive/

Archive an Employee

Archive an employee instead of deleting them. Archived employees are excluded from listings by default but their historical data is preserved.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/archive/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
POST/api/v2/employees/employees/:id/restore/

Restore an Employee

Restore a previously archived employee back to active status.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/restore/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
POST/api/v2/employees/employees/:id/checkin/

Check-in an Employee

Start tracking working time for an employee. You can optionally assign a project code to the check-in.

  • Name
    project_code
    Type
    string
    Description

    Optional project code to assign to this working session.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/checkin/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_code": "P-101"
  }'

You can also perform bulk check-ins by calling POST /api/v2/employees/employees/checkin/ without an employee ID. Use query parameters like employee_groups to filter which employees to check in.

POST/api/v2/employees/employees/:id/checkout/

Check-out an Employee

Stop tracking working time for an employee. This closes the current open timespan.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/checkout/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"
POST/api/v2/employees/employees/:id/custom-checkout/

Custom Check-out

Perform a manual check-out with a custom start and end time. The punchtime must be within 15 minutes in the past or 5 minutes in the future.

  • Name
    starttime
    Type
    string (ISO 8601)
    Description

    The check-in time to set. Required.

  • Name
    punchtime
    Type
    string (ISO 8601)
    Description

    The check-out time. Must be close to the current time.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/custom-checkout/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "starttime": "2024-06-20T08:00:00Z",
    "punchtime": "2024-06-20T16:30:00Z"
  }'
GET/api/v2/employees/employees/:id/settings/

Employee Settings

Retrieve or update the settings for a specific employee such as weekly working time and working days.

Retrieve Settings

curl -X GET "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/settings/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Update Settings

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/a1b2c3d4-e5f6-7890-abcd-ef1234567890/settings/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "weekly_working_time": 40,
    "weekly_work_days": 5
  }'
POST/api/v2/employees/employees/synch/csv/

Bulk Import (CSV)

Import or synchronize employees from a CSV file. Employees are matched by external_uid. New employees are created, existing ones are updated, and employees not present in the import can be archived.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/synch/csv/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: text/csv" \
  --data-binary @employees.csv

Response

{
  "created": 5,
  "updated": 12,
  "untouched": 83,
  "remaining": 0,
  "archived": 2
}
POST/api/v2/employees/employees/synch/json/

Bulk Import (JSON)

Import or synchronize employees using a JSON payload. Each entry requires an external_uid for matching.

  • Name
    external_uid
    Type
    string
    Description

    Unique external identifier for matching. Required.

  • Name
    first_name
    Type
    string
    Description

    Employee's first name.

  • Name
    last_name
    Type
    string
    Description

    Employee's last name.

  • Name
    email
    Type
    string
    Description

    Employee's email address.

  • Name
    external_id
    Type
    string
    Description

    Additional external identifier.

  • Name
    accounting_number
    Type
    string
    Description

    Accounting or personnel number.

  • Name
    group_id
    Type
    string (UUID)
    Description

    Employee group to assign.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/employees/employees/synch/json/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "external_uid": "EXT-001",
      "first_name": "Max",
      "last_name": "Mustermann",
      "email": "max@example.com"
    },
    {
      "external_uid": "EXT-002",
      "first_name": "Erika",
      "last_name": "Mustermann",
      "email": "erika@example.com"
    }
  ]'

Was this page helpful?