Skip to content

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.

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

Request body · required · application/json

Request schema
dialed_numberstring
Optional number being dialed, for example the user's own external caller identity number the call comes in on. Used only for the external DND check.
length: 0–64
example: +12125550100
targets*array<object>
The users or extensions to check, answered in this order.
items: 1–100
type*string
How to read `value`.
enum: user_id extension_id extension_number email
example: extension_number
value*string
A user id, extension id, extension number or user email, according to `type`.
length: 0–255
example: 101

Responses

One availability entry per target, in request order.
Response schema
data*array<object>
Each item — The availability verdict for ONE target of `POST /users/availability`. The response lists one entry per requested target, in request order. `available` is the single yes/no an integrator should act on; `checks` explains why. When the target cannot be resolved to a user of the calling PBX, `found`, `available` are `false` and `user_id`, `checks` and `extension` are `null`.
type*string
The target type, echoed from the request.
enum: user_id extension_id extension_number email
example: extension_number
value*string
The target value, echoed from the request.
example: 101
found*boolean
Whether the target resolved to a user of the calling PBX. `false` when it does not exist, belongs to another PBX, or is an extension that is not assigned to a user.
example: 1
user_id*string | null · uuid
The resolved user, or `null` when `found` is `false`.
example: 550e8400-e29b-41d4-a716-446655440000
available*boolean
`true` only when the target was found AND the user is enabled AND telephony is allowed AND the Tempus check passed AND (the user allows concurrent calls OR is not in a call) AND the dialed number is not blocked by DND.
example:
checks*object | null
The individual checks behind `available`. `null` when `found` is `false`.
user_enabled*boolean
Whether the user's status is enabled. A disabled user is never available.
example: 1
telephony_allowed*boolean
The user's "Allow telephony" setting. When off, the user is never available.
example: 1
tempus*object
The Tempus (time and attendance) check.
applies*boolean
Whether the PBX has the Tempus module. When `false` the check is skipped and `passed` is `true`.
example: 1
passed*boolean
With the Tempus module: `true` only when the user's current status group is `available` (no current status means `false`). Without the module: always `true`.
example: 1
status_group*string | null
The user's current status group, or `null` when there is no current status. Reported even when `applies` is `false`. Neither the status name nor any absence reason is ever returned.
enum: available unavailable busy meeting away null
example: available
in_call*boolean
Whether the user's own Voxbi app or softphone last reported being on a call. Calls on desk phones are not seen. Ignored (does not block) when `concurrent_calls` is `true`.
example: 1
concurrent_calls*boolean
Whether the user allows several concurrent calls. When `true`, `in_call` does not block.
example:
dnd*object
The user's Do Not Disturb state.
enforced*boolean
Whether the user is allowed to use DND. When `false`, DND never blocks, whatever the entries say.
example: 1
internal*boolean
Whether internal DND is active. Informational only, internal DND never blocks.
example:
external*array<object>
One entry per external DND row of the user, always returned.
caller_identity_id*string | null · uuid
The caller identity (the user's own number) the DND applies to. Null when the DND row has no caller identity.
example: 550e8400-e29b-41d4-a716-446655440010
number*string | null
The caller identity number. Null when the caller identity is missing or not part of this PBX; such an entry never blocks.
example: +12125550100
suffix*string | null
The caller identity suffix, if any.
active*boolean
Whether this external DND is currently active.
example:
dialed_number_blocked*boolean
`true` only when DND is `enforced`, a `dialed_number` was sent, and the active external DND on the caller identity number equal to `dialed_number` exists. Always `false` without `dialed_number`.
example:
extension*object | null
The resolved user's extension (a user has one at most), with what an AI agent needs to pick and dial it. `null` when `found` is `false` or the user has no extension.
id*string · uuid
The extension id.
example: 550e8400-e29b-41d4-a716-446655440020
number*string
The extension number.
example: 101
name*string | null
The extension name.
example: Billing
ai_prompt*string | null
The text describing what this extension handles, for an AI agent to choose a transfer target. `null` when none is set.
example: Handles billing questions and invoice disputes.
numbers*array<string>
The extension's direct numbers: each root number of the PBX followed by the extension number, as "+digits". Empty when the PBX has no root number or the extension number contains a wildcard (`*`).
[]string
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
Forbidden. The bearer token authenticated successfully but does not carry the scope this endpoint requires. Re-create the Integrations API key with the missing scope selected (Integrations > New integration > API key).
Response schema
messagestring
Unprocessable Parameters. Returned when the body is invalid (no targets, more than 100, unknown type or missing value).
Response schema
errorsobject
Validation messages keyed by field, using dot notation for array items. Returned as JSON whatever the Accept header.
Free-form object
post https://cockpit.voxbi.com/api/v1/users/availability
Base URL
Request sample
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);
Sample request
{ … }
"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"
}
]
}
{ … }
"data": [ … ]
{ … }
"type": "extension_number",
"value": "101",
"found": true,
"user_id": "550e8400-e29b-41d4-a716-446655440000",
"available": true,
"checks": { … },
"user_enabled": true,
"telephony_allowed": true,
"tempus": { … },
"applies": true,
"passed": true,
"status_group": "available"
},
"in_call": false,
"concurrent_calls": false,
"dnd": { … }
"enforced": true,
"internal": false,
"external": [ … ],
{ … }
"caller_identity_id": "550e8400-e29b-41d4-a716-446655440010",
"number": "+12125550100",
"suffix": null,
"active": false
}
],
"dialed_number_blocked": false
}
},
"extension": { … }
"id": "550e8400-e29b-41d4-a716-446655440020",
"number": "101",
"name": "Billing",
"ai_prompt": "Handles billing questions and invoice disputes.",
"numbers": [ … ]
"+12125550100101"
]
}
}
]
}
{ … }
"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
{ … }
"message": "Invalid ability provided."
}
Content-Type string
example: application/json
{ … }
"errors": { … }
"targets.0.type": [ … ],
"Target type must be one of: user_id, extension_id, extension_number, email."
],
"targets.1.value": [ … ]
"Each target needs a value."
]
}
}