API Docs
Voxbi Cockpit APIs
All endpoints

List overtime decisions for all employees (user)

Returns a paginated list of overtime decisions across all Tempus employees in the PBX tenant (the administrative view). Each item is serialized by the UserOvertimeDecisionResource. The caller must be authorized to view all overtime decisions for the tenant, otherwise the request is rejected with 403. Results may be filtered by overtime calculation period, decision type, lock state and company, and are sorted by -created_at by default.

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.
filter[overtime_calculation_period_id] query · string · uuid
Restrict results to a single overtime calculation period.
filter[decision_type] query · string
Restrict results to one or more decision types. Accepts a single value or a comma-separated list (for example `manual,automatic`).
filter[lock_states] query · string
Restrict results by lock state. `locked` returns processed (locked) decisions, `unlocked` returns decisions that have not been processed.
enum: locked unlocked
filter[company_id] query · string · uuid
Restrict results to a single Tempus company.
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 overtime decisions for all employees.
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 overtime decisions for this tenant.
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}/users-overtime-decisions
Base URL
Request sample 
curl -X GET 'https://cockpit.voxbi.com/api/v1/{pbx_id}/users-overtime-decisions' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/{pbx_id}/users-overtime-decisions', {
  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}/users-overtime-decisions',
    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}/users-overtime-decisions', 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