Check whether users can take a call right now (user, pbx)
Tells, for up to 100 users or extensions at once, whether each can take a (transferred) call right now. Built for live pre-checks, for example an AI voice agent shortlisting reachable people before asking the PBX to transfer. The PBX still runs its own checks when the transfer happens, so treat the answer as a pre-check, not a guarantee.
Authentication: a user bearer token, or an Integrations API key carrying the
extensions ability (the same gate as /extensions and /poll). The PBX is always the
caller's own; a target that belongs to another PBX is answered as not found.
Targets. Send 1 to 100 targets. Each target has a type (user_id, extension_id,
extension_number or email) and a value. The response has exactly one entry per
target, in request order. A duplicate target is answered each time it appears. A target
that does not exist, belongs to another PBX, is an extension not assigned to a user, or is
a partner support login (shadow user, never a call target) returns found: false,
available: false, user_id: null and checks: null. Emails are matched case-insensitively.
When is available true? Only when ALL of these hold:
found AND user_enabled AND telephony_allowed AND tempus.passed AND
(concurrent_calls OR NOT in_call) AND NOT dnd.dialed_number_blocked
| Check | What it means | Blocks when |
|---|---|---|
user_enabled |
The user's status is enabled. | The user is disabled. |
telephony_allowed |
The user's "Allow telephony" setting. | It is off. |
tempus |
Only when the PBX has the Tempus module (applies: true): the user's current status group must be available. Without the module the check is skipped (passed: true), but status_group is still reported. |
The module is on and the current status group is anything other than available, or there is no current status at all. |
in_call |
Live call flag reported by the user's own Voxbi app or softphone. Calls on desk phones are not seen. Ignored when the user allows concurrent calls (concurrent_calls: true). |
The user is reported in a call and does not allow concurrent calls. |
dnd |
The DND list is always returned. Only an active external DND on the user's caller identity number equal to dialed_number blocks. Internal DND never blocks. Nothing blocks when dialed_number is not sent. Nothing blocks when the user is not allowed to use DND (enforced: false). |
enforced is true, dialed_number is sent, and the external DND for that exact number is active (dialed_number_blocked: true). |
Dialed number matching. dialed_number is compared as + followed by its digits:
spaces and punctuation are ignored and a leading 00 counts as +. An external DND entry
matches when the dialed number equals its caller identity number plus its suffix. A
caller identity with the * suffix stands for the number followed by an extension: it
matches only the number followed by one of THIS user's own extension numbers. A DND entry
whose caller identity is missing is listed with number: null and suffix: null and
never blocks.
Not considered. These do not influence available: the right to disconnect (in the
PBX it only stops twinnings from ringing, the extension itself still rings; with Tempus on
it is already covered by the status group rule), call forwarding, VIP, and the
Voxbi.team / WebRTC permission.
Freshness. Live data (user settings, DND, Tempus time points, the in-call flag) is read on every call and the response is never cached. The Tempus status group is the current group only: the status name and any absence reason are never returned.
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>
application/jsonRequest body · required · application/json
+12125550100targets*array<object>
user_id extension_id extension_number emailextension_number101Responses
data*array<object>
user_id extension_id extension_number emailextension_number1011550e8400-e29b-41d4-a716-446655440000checks*object | null
11tempus*object
11available unavailable busy meeting away nullavailable1dnd*object
1external*array<object>
550e8400-e29b-41d4-a716-446655440010+12125550100extension*object | null
550e8400-e29b-41d4-a716-446655440020101BillingHandles billing questions and invoice disputes.numbers*array<string>
Authorization Token is missingerrorsobject
https://cockpit.voxbi.com/api/v1/users/availability
curl -X POST 'https://cockpit.voxbi.com/api/v1/users/availability' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'Content-Type: application/json' \
--data '{"dialed_number":"+12125550100","targets":[{"type":"extension_number","value":"101"},{"type":"email","value":"jane.smith@example.com"},{"type":"user_id","value":"550e8400-e29b-41d4-a716-446655440000"},{"type":"extension_id","value":"550e8400-e29b-41d4-a716-446655440020"}]}'
const response = await fetch('https://cockpit.voxbi.com/api/v1/users/availability', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${YOUR_TOKEN}`,
},
body: JSON.stringify({
"dialed_number": "+12125550100",
"targets": [
{
"type": "extension_number",
"value": "101"
},
{
"type": "email",
"value": "jane.smith@example.com"
},
{
"type": "user_id",
"value": "550e8400-e29b-41d4-a716-446655440000"
},
{
"type": "extension_id",
"value": "550e8400-e29b-41d4-a716-446655440020"
}
]
}),
});
const data = await response.json();
console.log(data);
import requests
response = requests.post('https://cockpit.voxbi.com/api/v1/users/availability',
headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
json={
"dialed_number": "+12125550100",
"targets": [
{
"type": "extension_number",
"value": "101"
},
{
"type": "email",
"value": "jane.smith@example.com"
},
{
"type": "user_id",
"value": "550e8400-e29b-41d4-a716-446655440000"
},
{
"type": "extension_id",
"value": "550e8400-e29b-41d4-a716-446655440020"
}
]
}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
'http' => [
'method' => 'POST',
'header' => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
'content' => '{
\"dialed_number\": \"+12125550100\",
\"targets\": [
{
\"type\": \"extension_number\",
\"value\": \"101\"
},
{
\"type\": \"email\",
\"value\": \"jane.smith@example.com\"
},
{
\"type\": \"user_id\",
\"value\": \"550e8400-e29b-41d4-a716-446655440000\"
},
{
\"type\": \"extension_id\",
\"value\": \"550e8400-e29b-41d4-a716-446655440020\"
}
]
}',
],
]);
$response = file_get_contents('https://cockpit.voxbi.com/api/v1/users/availability', false, $context);
$data = json_decode($response, true);
print_r($data);
{ … }
"targets": [ … ]
{ … },
{ … },
{ … },
{ … }
{ … }
"data": [ … ]
{ … }
"checks": { … },
"tempus": { … },
"dnd": { … }
"external": [ … ],
{ … }
"extension": { … }
"numbers": [ … ]
{ … }
private, must-revalidatekeep-aliveapplication/jsonOrigin6057{ … }
application/json