Devices

Devices are the physical time-tracking terminals of your organization. Use this API to inspect the connection status of your fleet, assign display names and projects to terminals, claim new hardware by serial number, and remove terminals from your account.

If your API token is restricted to specific permissions, it needs the matching scope for each operation: devices:view for listing and retrieving devices, devices:add for POST, devices:edit for PATCH/PUT, and devices:delete for DELETE. The authentication-modes and scan-modes endpoints only require a valid token. Requests without the required permission return 403 Forbidden.

The Device Object

Name
id
Type
string (UUID)
Description
Unique identifier for the device.
Name
created_at
Type
string (ISO 8601)
Description
Timestamp when the device record was created.
Name
modified_at
Type
string (ISO 8601)
Description
Timestamp when the device was last modified.
Name
model
Type
string
Description
Human-readable model label of the hardware, e.g. GEN5 WiFi, GEN5 Mini WiFi, GEN5 WiFi + Mobilfunk, Atlas Wifi, or Outdoor G1. Read-only.
Name
serial_number
Type
string
Description
The serial number printed on the hardware, e.g. K7X2M. Read-only.
Name
human_readable_name
Type
string
Description
Display name or location of the terminal, e.g. Main entrance. Maximum length 256 characters.
Name
authentication_mode
Type
string
Description
How employees authenticate at the terminal. One of the values returned by the authentication modes endpoint, currently rfid or aqrate. Defaults to rfid.
Name
scan_mode
Type
string
Description
How the terminal decodes RFID card identifiers. One of the values returned by the scan modes endpoint, e.g. auto or REVERSED_7B_BE_DEC. Defaults to auto.
Name
is_online
Type
boolean
Description
Whether the terminal is currently connected. A device counts as online if it reported a status within the last five minutes, or if its last connection is more recent than its last disconnection. Read-only.
Name
last_connection_at
Type
string (ISO 8601) or null
Description
When the terminal last connected.
Name
last_disconnection_at
Type
string (ISO 8601) or null
Description
When the terminal last disconnected.
Name
network_connections
Type
object
Description
Current network interfaces of the terminal. Contains a wifi and an eth object, each with is_connected (boolean) and ip (string or null). Read-only.
Name
project_id
Type
string (UUID) or null
Description
The project this terminal is assigned to, or null if it is not assigned to a project.

GET/api/v2/devices/devices/

List all Devices

Retrieve a paginated list of all devices assigned to your organization.

Query Parameters

Name
q
Type
string
Description
Search by serial number (partial, case-insensitive match).
Name
ids
Type
string
Description
Filter by device IDs (UUIDs), pipe-separated. Invalid UUIDs are ignored.
Name
serial_numbers
Type
string
Description
Filter by exact serial numbers, pipe-separated, e.g. serial_numbers=K7X2M|B4TQ9.
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/devices/devices/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
      "created_at": "2024-03-12T09:30:00",
      "modified_at": "2024-06-18T14:05:00",
      "model": "GEN5 WiFi",
      "serial_number": "K7X2M",
      "human_readable_name": "Main entrance",
      "authentication_mode": "rfid",
      "scan_mode": "auto",
      "is_online": true,
      "last_connection_at": "2024-06-18T14:04:12",
      "last_disconnection_at": "2024-06-17T22:10:45",
      "network_connections": {
        "wifi": {
          "is_connected": false,
          "ip": null
        },
        "eth": {
          "is_connected": true,
          "ip": "192.168.1.24"
        }
      },
      "project_id": "d4e5f6a7-b8c9-0123-defa-234567890123"
    }
  ]
}

GET/api/v2/devices/devices/:id/

Retrieve a Device

Get details of a specific device.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/devices/devices/e5f6a7b8-c9d0-1234-efab-567890123456/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

POST/api/v2/devices/devices/

Add a Device

Add a terminal to your organization. This does not create new hardware: it claims an existing, unassigned device by the serial number printed on it and assigns it to your account. The serial number is matched case-insensitively.

The request fails with a 400 Bad Request validation error on the serial_number field if the serial number is unknown, if the device is already assigned to your organization, or if it is still assigned to another account (in which case it has to be removed from that account first).

Name
serial_number
Type
string
Description
The serial number printed on the hardware. Required.
Name
human_readable_name
Type
string
Description
Display name or location for the terminal. Maximum length 256 characters.

On success, the API returns status 201 with the fields listed above. Use the list endpoint with the serial_numbers filter to fetch the full device object afterwards.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/devices/devices/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "B4TQ9",
    "human_readable_name": "Warehouse gate"
  }'

Response

{
  "serial_number": "B4TQ9",
  "human_readable_name": "Warehouse gate"
}

PATCH/api/v2/devices/devices/:id/

Update a Device

Update a device's settings. PUT requests to the same URL are also accepted and behave identically, since all writable fields are optional.

Name
human_readable_name
Type
string
Description
Display name or location of the terminal.
Name
authentication_mode
Type
string
Description
One of the values returned by the authentication modes endpoint.
Name
scan_mode
Type
string
Description
One of the values returned by the scan modes endpoint.
Name
project_id
Type
string (UUID) or null
Description
Assign the terminal to a project of your organization, or pass null to clear the assignment.

Request

curl -X PATCH "https://api.zeitstrom.com/api/v2/devices/devices/e5f6a7b8-c9d0-1234-efab-567890123456/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "human_readable_name": "Main entrance (Building A)",
    "project_id": "d4e5f6a7-b8c9-0123-defa-234567890123"
  }'

DELETE/api/v2/devices/devices/:id/

Remove a Device

Remove a device from your organization. The hardware record itself is not deleted: the device is unassigned from your account, its display name, project assignment, authentication mode, scan mode, and network settings are reset, and it can subsequently be claimed by another account. On success, the API returns status 204 with no content.

Request

curl -X DELETE "https://api.zeitstrom.com/api/v2/devices/devices/e5f6a7b8-c9d0-1234-efab-567890123456/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

GET/api/v2/devices/devices/authentication-modes/

List Authentication Modes

Retrieve the available choices for the authentication_mode field. Each choice has an id (the value to use in API requests) and a human-readable label. Labels are in German. The result can be narrowed with ?q= (matches the label, case-insensitive) and ?ids= (pipe-separated ids), and is paginated like the list endpoint.

Request

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

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "rfid",
      "label": "Mitarbeiterkarte"
    },
    {
      "id": "aqrate",
      "label": "aQrate"
    }
  ]
}

GET/api/v2/devices/devices/scan-modes/

List Scan Modes

Retrieve the available choices for the scan_mode field. The same q and ids query parameters as the authentication modes endpoint apply.

Request

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

Response

{
  "count": 5,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "auto",
      "label": "automatisch (10 Stellen, häufig)"
    },
    {
      "id": "ORDERED_4B_BE_DEC",
      "label": "ORDERED_4B_BE_DEC (10 Stellen, selten)"
    },
    {
      "id": "ORDERED_7B_BE_DEC",
      "label": "ORDERED_7B_BE_DEC (14 Stellen, selten)"
    },
    {
      "id": "REVERSED_4B_BE_DEC",
      "label": "REVERSED_4B_BE_DEC (10 Stellen, selten)"
    },
    {
      "id": "REVERSED_7B_BE_DEC",
      "label": "REVERSED_7B_BE_DEC (14 Stellen, häufig)"
    }
  ]
}