API Docs
Voxbi Cockpit APIs
All endpoints

Read the employee's overtime decision preference (user)

Returns the employee's standing overtime decision preference, the same row HR edits under "Decision Preferences" on the employee record, plus the options, bounds and defaults needed to render the form.

data is null when the employee has never saved a preference; in that case meta.configured is false and the company level rule applies. Read the starting values for the form from meta.defaults.

Self service only. The request is rejected with 403 when the authenticated user has no access to the tenant or the employee record is not their own, and with 404 when the employee cannot be found.

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. Must be the authenticated user's own employee record.
accept header · string
example: application/json

Responses

The current preference, or null when none has been saved.
Response schema
data*object
meta*object
Everything a client needs to render the preference form without hardcoding the enums: the selectable values with their translated labels, the bounds of the cap, and the values that apply when the employee has never saved a preference.
configured*boolean
Whether an employee level preference row exists. False means `data` is null and the company level rule applies.
example: 1
options*object
Selectable values keyed by field name. Each entry maps the stored value to its translated label.
auto_decision_policy*object
Free-form object
preferred_decision*object
Free-form object
rest_policy*object
Free-form object
limits*object
Accepted range for the cap, in both units.
min_seconds*integer · int32
example: 3600
max_seconds*integer · int32
example: 115200
min_hours*number · float
example: 1
max_hours*number · float
example: 32
defaults*object
The values the form should start from when `configured` is false.
auto_decision_policystring
example: skip_if_manual_decision
preferred_decisionstring
example: pay_up_to
rest_policystring
example: add_to_balance
max_secondsinteger · int32
example: 3600
max_hoursnumber · float
example: 1
is_activeboolean
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 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
get https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/user-overtime-decision-preference
Base URL
Request sample 
curl -X GET 'https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/user-overtime-decision-preference' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/{pbx_id}/user/{employee_id}/user-overtime-decision-preference', {
  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-preference',
    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-preference', false, $context);
$data = json_decode($response, true);
print_r($data);
{ … }
"data": { … },
"id": "9b1f0c62-4d0a-4e2f-9f43-6f4a5c8d1e70",
"scope": "employee",
"employee_id": "a24c68c0-92c0-4ca0-b749-84c6ddd671ed",
"auto_decision_policy": "force_auto_decision",
"auto_decision_policy_label": "Force auto-decision (override manual)",
"policy_reason": "Prefers time off over payout",
"preferred_decision": "increment_up_to",
"preferred_decision_label": "Increment balance up to X hours",
"max_seconds": 28800,
"max_hours": 8,
"rest_policy": "add_to_balance",
"rest_policy_label": "Add to balance",
"is_active": true,
"created_at": "2026-08-06 09:14:22",
"updated_at": "2026-08-06 10:02:51"
},
"meta": { … }
"configured": true,
"options": { … },
"auto_decision_policy": { … },
"skip_if_manual_decision": "Skip if manual decision exists",
"force_auto_decision": "Force auto-decision (override manual)",
"force_zero_overtime": "Force zero overtime (not eligible)"
},
"preferred_decision": { … },
"pay_up_to": "Pay up to X hours (specify max time)",
"increment_up_to": "Increment balance up to X hours (specify max time)"
},
"rest_policy": { … }
"add_to_balance": "Add to balance",
"drop": "Drop (ignore remaining hours)"
}
},
"limits": { … },
"min_seconds": 3600,
"max_seconds": 115200,
"min_hours": 1,
"max_hours": 32
},
"defaults": { … }
"auto_decision_policy": "skip_if_manual_decision",
"preferred_decision": "pay_up_to",
"rest_policy": "add_to_balance",
"max_seconds": 3600,
"max_hours": 1,
"is_active": true
}
}
}
{ … }
"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