API Docs
Voxbi Cockpit APIs
All endpoints

Get the Tempus profile for an employee (user)

Returns the consolidated Tempus profile for a single employee, assembled from the employee's active contract and company: the company, the contract dates, basic employee contact fields, and per-feature summaries (absence, home office allowance, overtime). The caller may only view their own profile: the request is rejected with 403 when the authenticated user has no access to the tenant or the employee record is not their own, with 404 when the employee or its linked user account cannot be found, and with 422 when the employee has no active contract to build a profile from.

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 profile is requested.
accept header · string
example: application/json

Responses

The assembled Tempus profile for the employee.
Response schema
employee*object
Basic identity details of the linked Tempus employee.
full_name*string
Full name of the employee, falling back to the linked user's name.
example: Jane Smith
email*string · email
Email address of the linked user account.
example: jane.smith@example.com
company*object
The company on the employee's active contract.
id*string | null · uuid
Identifier of the company. Null when the contract has no company.
example: 550e8400-e29b-41d4-a716-446655440001
name*string | null
Display name of the company. Null when the contract has no company.
example: Acme Corp
contract*object
The employee's active employment contract dates.
start*string | null · date
Start date of the active contract (a date, no time component).
example: 2024-01-01
end*string | null · date
End date of the active contract; null for an open-ended contract.
department_idstring | null · uuid
UUID of the department on the active contract, or null when none is set.
example: 550e8400-e29b-41d4-a716-446655440042
absence*object
Holiday and absence balances for the current calendar year, each an `HH:MM:SS` duration string. Always present.
possible*string
Total holiday entitlement available for the year.
example: 200:00:00
taken*string
Holiday already consumed during the year.
example: 80:00:00
remaining*string
Holiday still available to take.
example: 120:00:00
home_office*object
Home office allowance for the current year. `allowed`, `taken` and `remaining` (whole days) are present only when `enabled` is true.
enabled*boolean
Whether home office is enabled for the employee's company.
example: 1
allowedinteger · int32
Present only when enabled. Yearly allowance in days (the contract `ho_balance` override, else the company yearly cap).
example: 20
takeninteger · int32
Present only when enabled. Approved home office already taken this year, in whole days.
example: 5
remaininginteger · int32
Present only when enabled. Allowance still available, in whole days (`allowed` - `taken`). May be negative.
example: 15
overtime*object
Overtime calculation period summary. When `enabled` is false, only the `enabled` flag is present. When enabled, the additional fields below are included; `current_period` and `current` appear only when a period is active for the current date.
enabled*boolean
Whether overtime calculation periods are configured for the employee's company.
example: 1
decision_enabledboolean
Present only when enabled. Whether overtime decisions are configured for the company.
example: 1
compensatory_balancestring
Present only when enabled. Employee compensatory balance for the company, `HH:MM:SS` (may be negative). This is the AVAILABLE balance: the snapshot from the last LOCKED period. The running period's undecided accrual is reported separately under `current_accrual`, never folded in here.
example: 12:30:00
compensatory_balance_secondsinteger · int32
Same balance in seconds, so the client does not have to parse the string.
example: 45000
decision_preferenceobject | null
Present only when enabled. The employee's effective overtime decision preference: their own active preference, else the company's. Null when none is configured, in which case the company auto-decision policy applies at period end. `level` reports which of the two the values came from.
level*string
Whether these values come from the employee's own preference or the inherited company default.
enum: employee company
example: employee
preferred_decision*string | null
The default action for overtime (pay it out up to the cap, or add it to the balance up to the cap). Null when unset.
enum: pay_up_to increment_up_to null
example: increment_up_to
auto_decision_policy*string | null
What the system does at period end when the employee makes no manual decision.
enum: skip_if_manual_decision force_auto_decision force_zero_overtime null
example: skip_if_manual_decision
max_seconds*integer | null · int32
Cap in seconds that the preferred decision applies up to (for example 36000 = 10 hours). Null when uncapped.
example: 36000
rest_policy*string | null
What happens to overtime beyond the cap (carry it to the balance or drop it). Null when unset.
enum: add_to_balance drop null
example: add_to_balance
policy_reason*string | null
Free-text justification recorded with the preference. Null when none was given.
example: Per HR overtime policy.
current_periodobject
The overtime calculation period containing the current date. Present only when enabled and an active period exists.
id*string · uuid
Identifier of the overtime period.
example: 550e8400-e29b-41d4-a716-446655440000
start*string · date
First day of the overtime period.
example: 2026-01-01
end*string · date
Last day of the overtime period.
example: 2026-12-31
decision_possible_from*string | null · date
First day the employee may submit an overtime decision. Null when decisions are not enabled.
example: 2026-12-24
decision_possible_to*string | null · date
Last day the employee may submit an overtime decision. Null when decisions are not enabled.
example: 2026-12-31
current_accrualobject
Overtime accrued within the current period through the last COMPLETED day, split by day type. Always present (zeros when no period is open). Every figure is a signed BALANCE in seconds, with a pre-formatted `HH:MM:SS` twin and a ready-made `total`, so a client can display it as-is or convert. The range ends at YESTERDAY midnight — today is never counted. Today is still being lived, and the calculation charges the full workshift requirement against however much has been worked so far, so including it would show the rest of the day as undertime and make the figure climb hour by hour. Only finished days are stable enough to report as an accrued balance. Every overtime surface uses this same cutoff — this endpoint, `GET /{pbx_id}/user/{employee_id}/user-overtime-decision/getOvertime`, and the figure stored when a decision is submitted all report the identical number, so the accrual a client previews is the accrual the decision books.
business*integer · int32
Balance accrued on business (working) days, in seconds. Negative when the period is running below the required time.
example: 7200
business_formatted*string
Same figure as `HH:MM:SS`, sign glued to the value (`-02:08:49`). Hours may exceed 24.
example: 02:00:00
non_working*integer · int32
Balance accrued on non-working days, in seconds.
example: 3600
non_working_formatted*string
Same figure as `HH:MM:SS`, sign glued to the value.
example: 01:00:00
total*integer · int32
`business` + `non_working`, in seconds. The figure to display as the period accrual.
example: 10800
total_formatted*string
Same total as `HH:MM:SS`, sign glued to the value.
example: 03:00:00
travel_time*object
Travel time allowance. When `enabled` is false, only the `enabled` flag is present. When enabled, the employee may credit extra payable minutes to a day through POST /{pbx_id}/user/{employee_id}/travel-time, up to `max_per_day` times per date. The credited minutes are inserted immediately before the day's first status, so they extend the working day and count toward work time and overtime.
enabled*boolean
Whether travel time is enabled for this employee.
example: 1
minutes_per_requestinteger · int32
Present only when enabled. Payable minutes credited per request.
example: 30
max_per_dayinteger · int32
Present only when enabled. How many credits are allowed per date.
example: 1
used_todayinteger · int32
Present only when enabled. Credits already taken today.
example: 0
remaining_todayinteger · int32
Present only when enabled. Credits still available today.
example: 1
travel_time_allowed*boolean
Flat mirror of `travel_time.enabled`, for clients that read the flag directly. Always present and always consistent with the block.
example: 1
preferences*object
The employee user's Tempus display preferences. These describe how the user prefers dates rendered; they do not change the format of any field in this response (dates here are always ISO `Y-m-d`). Always present, with the user's stored choice or the system default.
date_format*string
The user's preferred date display format, as a PHP/`date()` format string. Falls back to the system default (`Y-m-d`) when the user has set no preference. A client can use this to render dates in the user's preferred style.
enum: d/m/Y m/d/Y Y-m-d d.m.Y
example: d.m.Y
validator*object | null
The employee's validator role, or `null` when they hold none. Null is the signal for whether to offer a validator section at all; a validator with an empty queue today is still a validator, so use `pending` for badges and empty states rather than to decide whether the section exists. `permissions` answers for both approval engines: the approval chains, and the older validator rules while a tenant still has them. The `companies`, `departments` and `employees` lists are the roster the older rules resolved, and are the values behind the filters for `GET /{pbx_id}/validator/employees`. Approval chains cannot produce that roster cheaply: a validator's place is a position in each requester's own chain, resolved through that person's contract, so for a tenant configured only with chains these three lists come back empty. Use `pending` and the queue endpoints (`GET /{pbx_id}/validator/pending-requests`, `pending-corrections`) instead, which answer from the chain itself.
permissions*object
Which validator modules this employee may act on.
holiday_requestsboolean
home_office_requestsboolean
time_point_corrections_requestsboolean
schedules_managementboolean
pending*object
How many requests of each type are waiting on this employee right now, counted from the approval rows addressed to them. Keyed the same way as `permissions`. `schedules_management` is always 0: schedule assignment is direct management, not a request queue.
holiday_requestsinteger
example: 3
home_office_requestsinteger
example: 1
time_point_corrections_requestsinteger
example: 0
schedules_managementinteger
example: 0
companies*array<object>
Distinct companies in the validator's scope.
idstring · uuid
namestring
departments*array<object>
Distinct departments in the validator's scope.
idstring · uuid
namestring
employees*array<object>
Lightweight list of the employees the validator may consult.
employee_idstring · uuid
namestring
validators*array<object>
The other direction from `validator`: the people who validate THIS employee's requests, one entry per validator, with the request types each of them covers. Where `validator` says what this employee may approve, `validators` says who approves this employee. Always present. Empty array when nobody validates the employee. Resolved from the older validator rules on the same basis as the `validator` block, so on a tenant configured only with approval chains (which cannot answer "who validates me" cheaply) it comes back empty; drive off `pending` and the queue endpoints there.
employee_id*string · uuid
The validator's Tempus employee id.
example: 550e8400-e29b-41d4-a716-446655440010
user_id*string | null · uuid
The validator's linked Cockpit user id, or null when they have no linked user.
example: 550e8400-e29b-41d4-a716-446655440011
name*string
The validator's display name (the PBX name-order preference is applied).
example: Jane Smith
scopes*array<string>
The request types this validator covers for the employee, in a stable order. A validator who covers more than one type appears once with every type listed.
[]string
enum: holiday_requests home_office_requests time_point_corrections_requests schedules_management
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 the requested tenant, or the requested employee record does not belong to the authenticated user.
Response schema
No response body.
Data Not Found. This error is returned when the requested data is not found.
Response schema
messagearray<string>
[]string
The employee has no active contract, so no profile can be produced.
Response schema
message*string
example: Employee has no active contract.
get https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/profile
Base URL
Request sample 
curl -X GET 'https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/profile' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/profile', {
  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}/profile',
    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}/profile', 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
No example for this status.