API Docs
Voxbi Cockpit APIs
All endpoints

List a specific employee's overtime decisions (user)

Returns a paginated list of overtime decisions recorded for a single Tempus employee within the PBX tenant. Each item is serialized by the UserOvertimeDecisionResource. When no filter[overtime_calculation_period_id] is supplied the list is automatically restricted to the employee's current overtime period. The caller must be authorized to view the employee's own decisions, otherwise the request is rejected with 403, and the employee must belong to the requested PBX tenant, otherwise 404 is returned.

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 Tempus employee.
filter[overtime_calculation_period_id] query · string · uuid
Restrict results to a single overtime calculation period. When omitted the current period is used automatically.
sort query · string
Sort order. Supports `created_at` and `overtime_calculation_period.start`, each prefixable with `-` for descending. Defaults to `-created_at`.
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 the employee's overtime decisions.
Response schema
dataarray<object>
Each item — A single overtime decision recorded against an employee for a given overtime calculation period. A decision captures how an employee's accrued overtime balance is resolved: how much is paid out, converted, reset, or carried forward, together with the resulting new balance. All duration fields (`decision_balance`, `decision_overtime`, `to_pay`, `to_increment`, `to_convert`, `to_reset`, `decision_new_balance`) are expressed as a whole number of seconds. They are returned as raw integer second counts, not as the HHH:MM display strings used in the admin UI. The related calculation period is only present in the response under `overtime_calculation_period` when it has been explicitly loaded by the endpoint (eager loaded); otherwise the field is omitted. **Rows for a period that is still running are computed live.** An employee decides once, part-way through the period, and then keeps working, so the figures stored on the row are a snapshot of that moment and go out of date immediately. On `GET /{pbx_id}/user/{employee_id}/user-overtime-decision`, such a row therefore reports `decision_balance`, `decision_overtime`, `to_increment` and `decision_new_balance` as they stand right now, against the decision the employee made, and `values_live` is true. Settled history — a processed row, or any row whose period has ended — is returned exactly as stored. See `values_live` below.
id*string · uuid
Unique identifier of the overtime decision.
read-only
example: 550e8400-e29b-41d4-a716-446655440000
mxvp_user_id*string · uuid
Identifier of the Pbx (tenant) that owns this decision.
example: 550e8400-e29b-41d4-a716-446655440001
ext_id*string | null
External extension identifier of the employee the decision applies to, resolved from the employee record. Null when the employee has no associated extension.
example: 1042
overtime_calculation_period_id*string | null · uuid
Identifier of the overtime calculation period this decision belongs to. Null when the decision is not linked to a specific period.
example: 550e8400-e29b-41d4-a716-446655440002
decision_type*string
How the decision was created. Defaults to `manual` when not otherwise set. `manual` decisions are entered by an operator, `automatic` decisions are produced by the system.
enum: manual automatic
example: manual
decision*string | null
The chosen resolution applied to the employee's overtime balance for the period (for example whether the overtime is paid out, converted, or reset). Null when no resolution has been selected yet.
example: pay_out
decision_balance*integer · int32
The employee's overtime balance, in seconds, carried into this period: the `decision_new_balance` of the last LOCKED period, or the contract's opening base when nothing has been locked yet. Maps to the model's `old_balance`.
example: 36000
decision_overtime*integer · int32
The overtime accrued during the period, in seconds, that this decision resolves. Counted over COMPLETED days only — the range ends at yesterday midnight, so neither the remaining workdays nor the hours still owed on today are counted as undertime. (A day carries its full shift requirement from the moment it begins, so a day in progress always reads negative.) Negative when the employee genuinely worked less than required over those completed days. Maps to the model's `overtime`. On a running period this is recomputed per request and keeps moving until the period closes; see `values_live`.
example: 7200
to_pay*integer · int32
Amount of overtime, in seconds, to be paid out to the employee. Never negative and never more than `decision_balance + decision_overtime`. This is the employee's own commitment to cash out a given amount, so it is NOT re-derived on a live row even as the accrual grows — it is only clamped down if it would exceed what is available. The growth lands on `to_increment` instead.
example: 3600
to_pay_extra*integer · int32
Additional overtime to pay out, in seconds. Always returned as 0 by this endpoint (reserved for future use).
example: 0
to_increment*integer · int32
Amount of overtime, in seconds, added to the employee's balance: `decision_overtime - to_pay`. Negative when the payout is larger than the period's accrual (the difference is drawn from the carried-in balance), or when the period itself ended in undertime.
example: 0
to_convert*integer · int32
Amount of overtime, in seconds, to be converted (for example into leave or another balance type).
example: 1800
to_reset*integer · int32
Amount of overtime, in seconds, to be reset (discarded) from the balance.
example: 0
decision_new_balance*integer · int32
The resulting overtime balance, in seconds, after applying this decision — what the employee has left once the payout is taken out. Derived by the system as `decision_balance + decision_overtime - to_pay - to_convert - to_reset`. Maps to the model's `new_balance`.
example: 38400
comment*string | null
Optional free-form note explaining or justifying the decision.
example: Carried forward at the employee's request
locked*boolean
Whether the decision has been processed and locked. True once the decision has a processing timestamp, after which it should be treated as final and immutable.
example:
values_live*boolean
Whether the duration fields on this row were computed just now rather than read from the decision snapshot. True only for a row whose period is still running and which has not been processed. Those figures are a moving target — they change as the employee keeps working, and are final only once the period closes and the decision is locked. False for all settled history, where the stored values are returned verbatim.
example:
created*string | null
Timestamp when the decision was created, formatted as `Y-m-d H:i:s` (for example `2024-03-01 08:29:07`). Null when the creation timestamp is not set.
read-only
example: 2024-03-01 08:29:07
overtime_calculation_periodobject
The related overtime calculation period this decision belongs to. Only present when the relation has been eager loaded by the endpoint; otherwise the field is omitted from the response.
idstring · uuid
Unique identifier of the overtime calculation period.
read-only
example: 550e8400-e29b-41d4-a716-446655440002
mxvp_user_idstring · uuid
Identifier of the Pbx (tenant) that owns the period.
example: 550e8400-e29b-41d4-a716-446655440001
company_idstring | null · uuid
Identifier of the Tempus company the period belongs to.
example: 550e8400-e29b-41d4-a716-446655440003
ext_idstring | null
External extension identifier of the employee, falling back to the period's user identifier when the employee has no extension.
example: 1042
startstring | null · date-time
ISO 8601 timestamp marking the start of the calculation period.
example: 2024-03-01T00:00:00Z
endstring | null · date-time
ISO 8601 timestamp marking the end of the calculation period.
example: 2024-03-31T23:59:59Z
lockedboolean
Whether the calculation period is locked and no longer editable.
example:
delete_datestring | null · date-time
ISO 8601 timestamp when the period was soft deleted. Null while the period is active.
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 caller is not authorized to view this employee's overtime decisions.
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}/user-overtime-decision
Base URL
Request sample 
curl -X GET 'https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/user-overtime-decision' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/user-overtime-decision', {
  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}/user-overtime-decision',
    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}/user-overtime-decision', 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