API Docs
Voxbi Cockpit APIs
All endpoints

List timepoints for an employee (user)

Returns a paginated list of clock-in/clock-out timepoints recorded for a single employee, newest first. The authenticated user must have access to the PBX tenant and be authorized to view the target employee's records. An optional date window can be applied with filter[from] and filter[to]; when both are supplied, filter[from] must not be after filter[to] and the range may not exceed 100 days, otherwise the request is rejected with 422. Each item is returned in the legacy timepoint shape (id, ext_id, time, status, comment, GPS coordinates, and an optional sub-status).

Three independent pieces of location data are returned and must not be conflated: location is the configured location record the employee selected; gpsLat / gpsLong / gpsTimestamp and the normalised device_gps block are where the device said it was, stored exactly as the client reported it; location_check compares the two and carries the geofence verdict (match / mismatch / unknown). The device coordinates are never replaced by the coordinates configured on the location.

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme
bearer
Bearer format
Bearer <token>
pbx_id path · string · uuid *
UUID of the PBX tenant.
employee_id path · string · uuid *
UUID of the employee whose timepoints are listed.
filter[from] query · string · date
Return timepoints whose start time is on or after this date (Y-m-d).
filter[to] query · string · date
Return timepoints whose start time is on or before this date (Y-m-d).
page query · integer
Page number to retrieve.
per_page query · integer
Number of items per page.
accept header · string
example: application/json

Responses

Paginated list of employee timepoints.
Response schema
dataarray<object>
Each item — A single Tempus time point (clock event) serialized in the legacy mobile-app format by the V1 `UserTimepointLegacyResource`. A time point records when an employee entered a given attendance status (for example "Working", "Break" or "Off"), optionally with a captured GPS location and a free-text comment. This object documents the exact keys returned by the resource, not the raw `tempus_time_points` columns. The `status` and `substatus` objects are flattened presentation views assembled from the related `TempusStatus` and `TempusSubStatus` records (their display style is read from each status's `style` JSON and its comment requirement from its `meta_data` JSON). The `gpsLong`, `gpsLat` and `gpsTimestamp` values are extracted from the time point's own `meta_data` JSON, tolerating several historical key spellings, and falling back to the normalised `device_gps` block for time points recorded since that block existed. The GPS fields (`gpsLong` / `gpsLat` / `gpsTimestamp` / `device_gps`) describe where the *device* said it was. The nested `location` object describes the *configured* location record the employee selected. `location_check` compares the two. The three are independent and must not be conflated. Several boolean-like flags (`status.comment`, `status.payable`, `substatus.comment`) are returned as the integers `1` or `0` rather than JSON booleans, preserving compatibility with the legacy client.
id*string · uuid
Unique identifier of the time point (clock event).
read-only
example: 550e8400-e29b-41d4-a716-446655440000
ext_id*string | null
External employee identifier resolved from the `employee_id` route parameter, used by the legacy client to correlate the event with its own employee record. Null when no external mapping exists for the employee.
example: EMP-10472
time*string | null · date-time
ISO 8601 timestamp marking when this status began (the time point's `start_time`). Null only when no start time is recorded.
example: 2024-03-01T08:29:07Z
status*object
The primary attendance status active from `time`, flattened from the related `TempusStatus` record together with its display style.
id*string | null · uuid
Identifier of the status. Null if the status is unavailable.
example: 550e8400-e29b-41d4-a716-446655440001
name*string | null
Human-readable status name shown to the employee.
example: Working
icon*string | null
CSS icon class used to render the status (from the status style's `icon_class`). Null when no icon is configured.
example: la la-briefcase
fontcolor*string | null
Foreground (text) colour for the status label, as a CSS colour value (from the status style's `font_color`). Null when unset.
example: #ffffff
backgroundcolor*string | null
Background colour for the status label, as a CSS colour value (from the status style's `bg_color`). Null when unset.
example: #2e7d32
css*string
Additional CSS class string for the status (from the style's `css`, falling back to `css_class`). Empty string when none is configured.
example: status-working
comment*integer · int32
Whether a comment is required when selecting this status: 1 if required, 0 otherwise. Derived from the status `meta_data` (`comment_required` flag or a `comment` entry in its `flags` list).
enum: 0 1
example: 0
payable*integer · int32
Whether time spent in this status is payable working time: 1 if payable, 0 otherwise.
enum: 0 1
example: 1
comment*string | null
Free-text comment attached to this time point. Falls back to the `comment` key inside the time point's `meta_data` when no dedicated comment column value is present. Null when no comment was recorded.
example: Started shift on site
gpsLong*number | string | null
Longitude of the captured GPS location, read from the time point's `meta_data` (accepting the `gpsLong`, `gps_long`, `longitude` or `lng` keys). The stored value may be a number or a string. Null when no location was captured.
example: -73.9857
gpsLat*number | string | null
Latitude of the captured GPS location, read from the time point's `meta_data` (accepting the `gpsLat`, `gps_lat`, `latitude` or `lat` keys). The stored value may be a number or a string. Null when no location was captured.
example: 40.7484
gpsTimestamp*string | integer | null
Timestamp at which the GPS location was captured, read from the time point's `meta_data` (accepting the `gpsTimestamp`, `gps_timestamp`, `timestamp` or `gps_time` keys). May be an ISO 8601 string or a Unix epoch value depending on the originating client. Null when no location was captured.
example: 2024-03-01T08:29:05Z
device_gpsobject | null
The coordinates the client reported, stored exactly as sent and never replaced by the coordinates configured on the selected location. This is the same fix the flat `gpsLat` / `gpsLong` / `gpsTimestamp` fields expose, in a normalised and typed form (a parsed timestamp, plus the reported accuracy, which the flat fields have no place for). Null when the time point carried no usable fix.
latitudenumber · double
example: 49.95
longitudenumber · double
example: 6.133
accuracy_mnumber | null · double
Accuracy radius of the fix in metres, as reported by the device.
example: 12.5
captured_atstring | null · date-time
The device's GPS timestamp, parsed. Null when unparseable or absent.
example: 2026-07-07T10:07:39+00:00
captured_at_rawstring | number | null
The GPS timestamp exactly as the client sent it.
example: 1783418859289
location_checkobject | null
Comparison of `device_gps` against the selected location's configured coordinates and geofence radius: the signal that a status was recorded against a location the employee was not actually at. Same shape and semantics as on the `TempusTimePoint` model. Null when the time point has neither a device fix nor a location, and on time points written before this check existed.
location_idstring | null · uuid
example: 550e8400-e29b-41d4-a716-446655440010
location_latitudenumber | null · double
example: 49.6008
location_longitudenumber | null · double
example: 6.133
geofence_radius_minteger | null
example: 150
distance_minteger | null
Metres between the device fix and the location's configured point. Recorded whenever both have coordinates, even with no radius set.
example: 38957
within_geofenceboolean | null
Whether the fix falls inside the geofence, with the device's own reported accuracy allowed as tolerance. Null when no verdict was possible.
example:
verdictstring
enum: match mismatch unknown
example: mismatch
reasonstring | null
Why the verdict is `unknown`. Null otherwise.
enum: no_device_gps no_location location_without_coordinates no_geofence_radius null
substatus*object | null
The first associated sub-status for this time point (a refinement of the main status, for example a specific break type), flattened from the related `TempusSubStatus` record together with its display style. Null when no sub-status is attached.
id*string · uuid
Identifier of the sub-status.
example: 550e8400-e29b-41d4-a716-446655440002
name*string | null
Human-readable sub-status name.
example: Lunch break
icon*string | null
CSS icon class used to render the sub-status (from its style's `icon_class`). Null when no icon is configured.
example: la la-coffee
fontcolor*string | null
Foreground (text) colour for the sub-status label, as a CSS colour value (from its style's `font_color`). Null when unset.
example: #000000
backgroundcolor*string | null
Background colour for the sub-status label, as a CSS colour value (from its style's `bg_color`). Null when unset.
example: #fff3e0
css*string
Additional CSS class string for the sub-status (from its style's `css`, falling back to `css_class`). Empty string when none is configured.
example: substatus-lunch
comment*integer · int32
Whether a comment is required when selecting this sub-status: 1 if required, 0 otherwise. Derived from the sub-status `meta_data`.
enum: 0 1
example: 0
linksobject
firststring
The first page of the resource
example: http://localhost/api/v1/resources?page=1
laststring
The last page of the resource
example: http://localhost/api/v1/resources?page=1
prevnull | string
The previous page of the resource
nextnull | string
The next page of the resource
metaobject
current_pageinteger
The current page of the resource
≥ 1
example: 1
fromnull | integer
The first item of the resource
≥ 1
example: 1
last_pageinteger
The last page of the resource
≥ 1
example: 1
linksarray<object>
urlstring | null
The url of the resource (null for the boundary prev/next links)
example: http://localhost/api/v1/resources?page=1
labelstring
The label of the resource
example: first
activeboolean
The status of the resource
example: 1
pathstring
The path of the resource
example: http://localhost/api/v1/resources
per_pageinteger
The number of items per page of the resource
≥ 1
example: 15
tonull | integer
The last item of the resource
≥ 1
example: 1
totalinteger
The total number of items of the resource
≥ 0
example: 1
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
The authenticated user has no access to this PBX tenant or is not authorized to view the target employee's records.
Response schema
No response body.
Data Not Found. This error is returned when the requested data is not found.
Response schema
messagearray<string>
[]string
Unprocessable Parameters. This error is returned when a parameter is not valid.
Response schema
messagestring
example: The given data was invalid.
errorsobject
filterarray<string>
[]string
sortarray<string>
[]string
pagearray<string>
[]string
per_pagearray<string>
[]string
get https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/timepoints
Base URL
Request sample 
curl -X GET 'https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/timepoints' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/timepoints', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

const data = await response.json();
console.log(data);
import requests

response = requests.get('https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/timepoints',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/timepoints', false, $context);
$data = json_decode($response, true);
print_r($data);
No example for this status.
{ … }
"error": "Authorization Token is missing"
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
No example for this status.
{ … }
"message": [ … ]
"Data not found"
]
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"errors": { … }
"filter": [ … ],
"The filter field must be an array."
],
"sort": [ … ],
"The sort field must be a string."
],
"page": [ … ],
"The page field must be an integer."
],
"per_page": [ … ]
"The per page field must be an integer."
]
}
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57