Physical Tokens

Physical tokens are the RFID badges employees use to check in and out at hardware terminals. This API manages your organization's pool of registered badges. To assign a badge to an employee, set the employee's physical_token_id field via the Employees API — it holds the token's id (the printed card number).

If your API token is restricted to specific permissions, it needs the matching scope for each operation: physical_tokens:view for GET requests, physical_tokens:add to register tokens, and physical_tokens:delete to remove them. Requests without the required permission return 403 Forbidden.

The Physical Token Object

Unlike most other resources, physical tokens are not identified by a UUID: the id is the numeric card number printed on the badge. By default, only the id field is returned; use the fields query parameter to request the employee-related fields.

Name
id
Type
string
Description
The card number printed on the badge, 10 or 17 digits. Leading zeros are preserved, so the value is always a string. Read-only.
Name
employee__id
Type
string (UUID) or null
Description
UUID of the employee the token is assigned to, or null if the token is unassigned. Only returned when requested via fields. Read-only.
Name
employee__first_name
Type
string or null
Description
First name of the assigned employee, or null if unassigned. Only returned when requested via fields. Read-only.
Name
employee__last_name
Type
string or null
Description
Last name of the assigned employee, or null if unassigned. Only returned when requested via fields. Read-only.

GET/api/v2/devices/physical-tokens/

List all Physical Tokens

Retrieve a paginated list of your organization's physical tokens, ordered by card number.

Query Parameters

Name
fields
Type
string
Description
Pipe-separated list of fields to return for each token. Options are id, employee__id, employee__first_name, and employee__last_name. Defaults to id.
Name
q
Type
string
Description
Search for tokens whose card number contains the query term.
Name
ids
Type
string
Description
Restrict the result set to specific tokens by passing a pipe-separated list of card numbers, e.g. ids=0005673921|3405021956.
Name
type
Type
string
Description
Filter by assignment state: available returns only tokens without an assigned employee, assigned returns only tokens with one, and all returns everything. Invalid values silently fall back to all. Defaults to all.
Name
additional
Type
string
Description
Card number of one extra token to include as the first result, even if it does not match the other filters. The token must already be registered to your organization.
Name
limit
Type
integer
Description
Number of results per page. Defaults to 1000, 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/physical-tokens/?fields=id|employee__id|employee__first_name|employee__last_name" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "0005673921",
      "employee__id": "508d5250-7399-4b65-a574-3da53d9ddc25",
      "employee__first_name": "Anna",
      "employee__last_name": "Schmidt"
    },
    {
      "id": "3405021956",
      "employee__id": null,
      "employee__first_name": null,
      "employee__last_name": null
    }
  ]
}

GET/api/v2/devices/physical-tokens/:id/

Retrieve a Physical Token

Get a single physical token by its printed card number. The fields query parameter works the same as on the list endpoint; without it, only the id field is returned.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/devices/physical-tokens/0005673921/?fields=id|employee__id" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "0005673921",
  "employee__id": "508d5250-7399-4b65-a574-3da53d9ddc25"
}

POST/api/v2/devices/physical-tokens/

Create Physical Tokens

Register one or more physical tokens with your organization in a single request. Each card number must consist of digits only and be exactly 10 or 17 digits long. 10-digit numbers must be below 4294967296 (2^32) and 17-digit numbers below 72057594037927936 (2^56); otherwise the request fails with a 400 validation error. Empty strings in the list are ignored.

If any of the card numbers is already registered, the whole request fails with a 400 validation error — unless you pass skip_checks: ["exists"], in which case already-registered tokens are left unchanged and returned alongside the newly created ones.

On success, the API returns status 201 with the list of token objects.

Name
ids
Type
array of strings
Description
The printed card numbers to register, each 10 or 17 digits. Required.
Name
skip_checks
Type
array of strings
Description
Set to ["exists"] to allow card numbers that are already registered instead of rejecting the request.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/devices/physical-tokens/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["3405021956", "00042761015382290"]
  }'

Response

[
  {
    "id": "3405021956"
  },
  {
    "id": "00042761015382290"
  }
]

POST/api/v2/devices/physical-tokens/delete/

Delete Physical Tokens

Remove one or more physical tokens from your organization. All listed card numbers must exist; if at least one does not, the request fails with a 400 validation error and nothing is deleted. On success, the API returns status 204 with no content.

Name
ids
Type
array of strings
Description
The printed card numbers of the tokens to delete. Required.

Request

curl -X POST "https://api.zeitstrom.com/api/v2/devices/physical-tokens/delete/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["3405021956"]
  }'