Concepts
Workers and watches
How the API identifies each person and their watch: company identifier, optional name by contract, battery, whether it’s being worn and last connection.
Every person wears a watch. The API exposes them separately —workers and watches— and links them to each other. Both require the workers:read scope.
Workers
GET /v1/workers and GET /v1/workers/{id}.
| Field | What it is |
|---|---|
id | The worker’s UUID in SafeOnuba. |
external_id | Their code in your company, the one from your personnel system. null if none has been given. |
name | Full name. Only if the contract includes it; otherwise the property doesn’t appear. |
contractor | The contractor they work for, or null. |
role | Their job, or null. |
is_active | Whether they are registered. |
device | The watch assigned to them. |
date_last_seen | The more recent of their last position and the watch’s last contact. |
No names
Workers’ names are optional by contract. Without them, the API identifies each person by their external_id, the same code your company already uses. To cross-reference with your personnel or access control system, use that field, which doesn’t depend on the contract including names.
The same approach applies everywhere: in worker inside an alert, in the list of who is missing and in positions.
What your client sees
The API sees the same as a person in the dashboard with those permissions, including the scope by contractor. A worker your identity can’t see responds 404, as if they didn’t exist.
Watches
GET /v1/devices returns the watches with their status.
| Field | What it is |
|---|---|
id, serial | Identifier and serial number. |
model | Model, or null. |
status | The watch’s status in the inventory. |
battery | Battery as a percentage, or null. |
worn | Whether it is being worn. null if unknown, because the watch has no wrist sensor. |
date_last_seen | Last contact. |
worker | Who it is assigned to. |
| status | What it means |
|---|---|
active | In use. |
inactive | Out of use. |
maintenance | Under maintenance. |
lost | Lost. |
A watch that stops communicating or runs out of battery generates an alert (device_offline, low_battery). You don’t need to poll this list in a loop to find out: they arrive by webhook like any other alert.
There are never vital signs
Neither the worker nor the watch carries pulse, temperature or any other vital sign, individually or aggregated. See Privacy and security.