Voxbi Cockpit API
REST API for the Voxbi Cockpit PBX platform. Use it to manage users, extensions, SIP devices, phone numbers, call flows, IVRs, queues, schedules, and related telephony resources.
All resources are scoped to a PBX tenant. The authenticated identity determines which PBX(es) you can access.
Every request must be authenticated. See Authentication for the available schemes.
Principal-conditional fields
Most resources are reachable by two kinds of token: a user-owned token
(the cockpit/mobile Bearer token) and a PBX-owned API key (created on the
Integrations page). A few response fields are per-user and therefore depend
on which kind of token you use: they are returned for user-owned tokens and
omitted entirely for PBX API-key tokens (a PBX has no per-user state).
Such fields are flagged PRINCIPAL-CONDITIONAL in their description -
examples: is_favorite on extensions and contacts, and editable on contacts.
Embedding related resources
List and detail endpoints accept an ?include= query parameter: a
comma-separated list of related resources to embed. Each endpoint documents
its own allowed values; anything not in that allow-list is rejected, and
nothing is embedded unless you ask for it.
Some relations are dot-nested, which lets you choose how deep to go. For
example, on an extension you can request user to embed just the user, or
user.groups to embed the user and its groups (you do not have to load
the parent separately). Combine several with commas, e.g.
?include=user.groups,sipDevice.
Rate limiting
Requests are rate limited per API key (per PBX). The default budget is 120 requests per minute; it may be higher depending on your plan. Every response reports your current budget so you do not have to hard-code the number:
X-RateLimit-Limit- the limit applied to this requestX-RateLimit-Remaining- requests left in the current window
When you exceed the limit the API responds with 429 Too Many Requests and a
Retry-After header (seconds to wait before retrying). Always read these
headers rather than assuming a fixed rate: the budget can change per plan, and
a few endpoints have their own stricter limit. The clearest example is
Push the PBX configuration, which is capped at 1 request per minute - that
endpoint documents its own limit and 429 response.
-
The production API server
https://cockpit.voxbi.com/api/v1 -
The staging API server
https://staging-cockpit.voxbi.com/api/v1 -
The development API server
https://dev-cockpit.voxbi.com/api/v1
- bearerAuth Bearer token
- ApiKeyAuth API key in header "Authorization"
- PbxServerAuth Bearer token
- PbxApiKey Bearer token
- IntegrationApiKey Bearer token
No matching endpoints
Nothing matches “”. Try a different search term.
Telephony
Authentication
Every endpoint uses bearer token authentication: send your token in the Authorization header on every request:
Authorization: Bearer <token>
There are two kinds of token:
- User token - obtained by calling
POST /loginwith a user's credentials. It inherits that user's permissions and is scoped to their PBX(es). There is no separate "global" token; broader access comes from logging in as a user with broader role assignments (e.g. a super-admin). - PBX API key - created by the customer on the Cockpit Integrations page (an "API key" integration). It is owned by the PBX and limited to the scopes selected when the key was created.
Both kinds authenticate against the same endpoints. Which fields a response contains can depend on the token type: a few per-user fields are returned for user tokens and omitted for PBX API keys (see Principal-conditional fields above, and the PRINCIPAL-CONDITIONAL note on the affected fields).
Per-operation auth requirements are listed under each endpoint's Security section.
/login
Log in with email and password (public)
get
/me
Get the authenticated user (user)
get
/user
Get the authenticated user record (user)
get
/magic-login/{token}
Log in with a magic link token
post
/passwordless/login
Request Passwordless Login Code
post
/passwordless/verify
Verify Passwordless Login Code
post
/passwordless/resend
Resend Passwordless Login Code
post
/request-password-reset
Request a password reset email
post
/reset-password
Reset Password
post
/edit-password
Set a new password
AI configuration
Read-only aggregated AI setup for a PBX (global prompt, labels, keyword tree, per-extension and per-group prompts, AI profile and feature flags). Read with a PBX API key carrying the ai-configuration scope.
Calls
Endpoints for initiating and managing outbound calls.
Call Flows
Define how inbound calls are routed through your PBX. A call flow chains ordered steps (transfer, IVR, voicemail, queue, schedule) that the system evaluates per call.
Call Flow Steps
Individual steps belonging to a call flow. Each step has a type and a target (extension, queue, sound file, IVR, etc.) and is executed in order.
IVR
Interactive Voice Response menus that play a prompt and route the caller based on the key they press.
IVR Steps
Individual menu options inside an IVR. Each step maps a digit (or timeout) to a destination.
Queues
Call queues that hold callers until an agent is available, with configurable strategies and music on hold.
Schedules
Time-of-day rule sets used by call flows to route differently inside vs outside business hours.
Phone Numbers
External DIDs owned by the PBX. Numbers are linked to call flows, users, or queues for inbound routing.
Caller Identities
Caller identities represent the outbound phone numbers (and optional suffixes) available to the authenticated user when placing calls. Each identity is linked to a phone number and a target entity (User, PBX, Group, or SIP device).
SIP Carriers
Upstream SIP trunks used for outbound calls and number termination.
SIP Devices
Physical or soft SIP endpoints (deskphones, softphones, ATAs) registered against the PBX.
Extensions
Internal dial numbers assigned to users, devices, queues, and other PBX entities.
Twinning
Ring an external number in parallel with the user's extension.
/twinnings
List twinning
get
/twinnings/{id}
Get a Twinning
get
/users/{user}/twinnings
List a user's twinnings (user)
post
/users/{user}/twinnings
Create a twinning for a user (user)
get
/users/{user}/twinnings/{twinning}
Get a user's twinning (user)
put
/users/{user}/twinnings/{twinning}
Update a user's twinning (user)
patch
/users/{user}/twinnings/{twinning}
Update a user's twinning (user)
delete
/users/{user}/twinnings/{twinning}
Delete a user's twinning (user)
Do Not Disturb
Manage Do Not Disturb rules for users and extensions.
/dnds
List DND rules for the authenticated user
get
/users/{user}/dnds
List DNDs for a user
post
/users/{user}/dnds
Create a DND for a user
put
/users/{user}/dnds/{userDnd}
Update a DND for a user
post
/users/{user}/dnds/bulk
Bulk-update DND rules for a user
post
/users/{user}/dnds/all-external
Toggle DND on every external extension of a user
post
/users/{user}/dnds/all
Toggle DND on every extension of a user
Users
PBX users. Each user owns an extension, devices, presence status, and forwarding rules.
/register-device
Register a device for push notifications
post
/unregister-device
Unregister a device from push notifications
post
/cleanup-old-tokens
Clean up old push notification tokens
post
/notify-device
Send a push notification to a device
get
/layout
Get the active Status Changer layout (user)
get
/users
List user
get
/users/{id}
Get an User
get
/users/{email}/webrtc
Get an user WebRTC configuration by Email
get
/qr-code
Get QR code for authenticated user
get
/soop-status
Get SOOP status for authenticated user
post
/favorites
Toggle favorite user
get
/poll
Poll extensions with DND, status and in-call flags (user)
get
/in-call
Read the authenticated user's in-call flag (user)
post
/in-call
Set the authenticated user's in-call flag (user)
get
/user/devices
List devices for authenticated user
post
/user/devices
Register a device for authenticated user
patch
/user/devices/{deviceIdOrToken}
Update a device for authenticated user
delete
/user/devices/{deviceIdOrToken}
Delete a device for authenticated user
post
/dnd
Set User DND
get
/users/{user}/forwards
List forwards for a user
post
/users/{user}/forwards
Create a forward for a user
put
/users/{user}/forwards/{forward}
Update a forward for a user
delete
/users/{user}/forwards/{forward}
Delete a forward for a user
post
/users/{user}/favorite-users
Add a favorite user (user)
delete
/users/{user}/favorite-users/{favorite_user}
Remove a favorite user (user)
get
/users/{user}/phone-buttons/resolved
Get resolved phone buttons for a user
get
/users/{user}/phone-buttons/resolved-detailed
Get resolved detailed phone buttons for a user
get
/users/{user}/phone-buttons/preview-config
Get phone buttons preview config for a user
get
/users/{user}/phone-buttons
List phone buttons for a user
post
/users/{user}/phone-buttons
Create a phone button for a user
get
/users/{user}/phone-buttons/{phoneButtonId}
Get a phone button for a user
put
/users/{user}/phone-buttons/{phoneButtonId}
Replace a phone button for a user
patch
/users/{user}/phone-buttons/{phoneButtonId}
Partially update a phone button for a user
delete
/users/{user}/phone-buttons/{phoneButtonId}
Delete a phone button for a user
get
/users/{user}/user-settings
List settings for a user
post
/users/{user}/user-settings
Create a setting for a user
get
/users/{user}/user-settings/{type}
Get a setting for a user by type
put
/users/{user}/user-settings/{type}
Replace a setting for a user by type
patch
/users/{user}/user-settings/{type}
Partially update a setting for a user by type
delete
/users/{user}/user-settings/{type}
Delete a setting for a user by type
get
/users/{user}/user-groups
List user-groups for a user
post
/users/{user}/user-groups
Add a user-group to a user
get
/users/{user}/user-groups/{userGroup}
Get a user-group for a user
patch
/users/{user}/user-groups/{userGroup}
Partially update a user-group for a user
delete
/users/{user}/user-groups/{userGroup}
Remove a user-group from a user
get
/users/{user}/right-to-disconnect
Get right-to-disconnect settings for a user
put
/users/{user}/right-to-disconnect
Update right-to-disconnect settings for a user
post
/change-status
Change presence status for the authenticated user (user)
get
/timepoints
List presence timepoints for the authenticated user (user)
get
/workTimes
Get accumulated work times for the authenticated user (user)
User Groups
Manage user groups for organizing users within a PBX.
/user-groups
List user groups
post
/user-groups
Create a user-group
post
/user-groups/update-positions
Update positions of user-groups
get
/user-groups/{userGroupId}
Get an user-group
patch
/user-groups/{userGroupId}
Partially update a user-group
delete
/user-groups/{userGroupId}
Delete a user-group
post
/user-groups/{userGroupId}/add-users
Add users to a user-group
post
/user-groups/{userGroupId}/remove-users
Remove users from a user-group
Groups
Ring groups that dial multiple destinations simultaneously or in sequence.
Pools
Extension pools and their user assignments.
Statuses
Top-level presence values (e.g. Available, Busy, Away) that users can broadcast.
Substatuses
Refinements under a parent status (e.g. Away > Lunch, Away > Meeting).
Voxbi Group Tabs
Custom tab configurations for Voxbi group views.
Pbxes
The tenant container. Every other resource is scoped to a PBX.
Locations
Physical offices or sites associated with the PBX, used for emergency call routing and reporting.
Languages
Languages available for sound files, voice prompts, and user preferences.
Sound Files
Audio files used for greetings, prompts, music on hold, and voicemail.
Contacts
Shared address book entries available across the PBX.
/contacts
List contact
post
/contacts
Create a contact
get
/contacts/{contact}
Get a Contact
put
/contacts/{contact}
Update a contact
delete
/contacts/{contact}
Delete a contact
post
/contacts/{id}/block
Block a contact
post
/contacts/{id}/unblock
Unblock a contact
post
/contacts/favorite
Toggle a contact as favorite
get
/source/{source}/contacts
Get contacts from a specific source
Contact Imports
Import personal contacts from a CSV or Excel file via a guided upload, map, and confirm flow. Each import and every contact it creates is private to the authenticated user.
/contacts/imports
List your contact imports (user)
post
/contacts/imports
Upload a contact import file (user)
get
/contacts/imports/sample
Download a sample import file (user)
get
/contacts/imports/{id}
Get one of your contact imports (user)
delete
/contacts/imports/{id}
Delete one of your contact imports (user)
get
/contacts/imports/{id}/settings
Get parsing settings for an import (user)
put
/contacts/imports/{id}/settings
Update parsing settings for an import (user)
get
/contacts/imports/{id}/mapping-options
Get column mapping options for an import (user)
put
/contacts/imports/{id}/mappings
Save the column mapping for an import (user)
post
/contacts/imports/{id}/confirm
Confirm and start an import (user)
Images
Retrieve images (avatars, logos) associated with models.
Webhooks
Inbound webhooks from third-party services (e.g. Famulor post-call events).
Phone Number Orders
Customer-facing endpoints for the Nexus number-order proxy. Use these to check whether a phone number can be provisioned at a given address, place an order (with KYC documents attached), retrieve an order's status, edit and retry an order that failed submission, list the phone numbers already owned by the PBX, and attach a call flow to a specific number.
Authentication is the PBX API key (one token per PBX); every response is scoped to that PBX.
/numbers
List phone numbers on the PBX
put
/numbers/{id}/call-flow
Attach a call flow to a phone number
post
/numbers/orders/check
Check whether a phone number can be ordered at a given address
post
/numbers/orders
Place a phone number order
get
/numbers/orders/{id}
Get a phone number order
post
/numbers/orders/{id}
Edit and retry a failed phone number order
Push configuration
Push the PBX configuration so pending changes take effect - the programmatic equivalent of the "Push configuration" button in Cockpit. PBX API key auth; rate limited to 1 request/minute per PBX.
Odoo Installer
Endpoints consumed by the Voxbi Installer module running inside a customer's Odoo.
Register the Odoo integration, poll the install status, read it back, and update or
re-run it. Authenticated with a customer API key carrying the odoo-installer
ability; the PBX is resolved from the key.
/odoo-installer/register-install
Register an Odoo installation (pbx)
get
/odoo-installer/install-status
Get the Odoo installation status (pbx)
get
/odoo-installer/get-integration
Get the Odoo integration (pbx)
post
/odoo-installer/update-and-fix-integration
Update and re-run the Odoo integration (pbx)
Tempus
Absences
Employee absence requests, absence records, and validator decisions on them.
/{pbx_id}/absences
List absences for the tenant (user)
get
/{pbx_id}/user/{employee_id}/absences
List absences for a specific employee (user)
get
/{pbx_id}/absence-requests
List pending absence requests for a PBX (user)
get
/{pbx_id}/user/{employee_id}/absence-requests
List absence requests for a specific employee (user)
post
/{pbx_id}/user/{employee_id}/absence-requests
Create an absence request for a specific employee (user)
put
/{pbx_id}/user/{employee_id}/absence-requests/{absence_request_id}
Update a pending absence request for an employee (user)
post
/{pbx_id}/user/{employee_id}/absence-requests/{absence_request_id}/cancel
Cancel an absence request, or take back its cancellation (user)
post
/{pbx_id}/user/{employee_id}/absence-removal-requests
Request removal of an approved legal holiday absence (user)
get
/{pbx_id}/absence-requests/{absence_request_id}/validations
List validations for an absence request (user)
post
/{pbx_id}/absence-requests/{absence_request_id}/validations
Submit a validation decision for an absence request (user)
Home office
Home office requests, home office calendars, and validator decisions on them.
/{pbx_id}/home-office-requests
List home office requests (tenant-wide, validator-scoped)
get
/{pbx_id}/user/{employee_id}/home-office-requests
List a specific employee's home office requests
post
/{pbx_id}/user/{employee_id}/home-office-requests
Request home office days for an employee (user)
post
/{pbx_id}/user/{employee_id}/home-office-requests/cancel
Withdraw home office days, or take back their cancellation (user)
get
/{pbx_id}/home-office-requests/{home_office_request_id}/validations
List validations for a home office request (user)
post
/{pbx_id}/home-office-requests/{home_office_request_id}/validations
Submit a validation decision for a home office request (user)
post
/{pbx_id}/home-office-requests/validations
Validate several home office day-rows at once
get
/{pbx_id}/home-office-calendars
List home office calendars across employees (user)
get
/{pbx_id}/user/{employee_id}/home-office-calendars
List home office calendars for one employee (user)
Corrections
Time point correction requests and validator decisions on them.
/{pbx_id}/corrections
List timepoint corrections for the tenant (user)
get
/{pbx_id}/user/{employee_id}/corrections
List timepoint corrections for an employee (user)
post
/{pbx_id}/user/{employee_id}/corrections
Create a timepoint correction for an employee, edit alias (user)
post
/{pbx_id}/user/{employee_id}/corrections/add
Add-a-missing-timepoint correction (user)
post
/{pbx_id}/user/{employee_id}/corrections/edit
Edit-an-existing-timepoint correction (user)
post
/{pbx_id}/user/{employee_id}/corrections/delete
Delete-a-timepoint correction (user)
get
/{pbx_id}/user/{employee_id}/corrections/{correction_id}
Get a timepoint correction for an employee (user)
put
/{pbx_id}/user/{employee_id}/corrections/{correction_id}
Cancel a timepoint correction for an employee (user)
get
/{pbx_id}/corrections/{correction_id}/validations
List validation decisions for a time-point correction (user)
post
/{pbx_id}/corrections/{correction_id}/validations
Submit a validation decision for a time-point correction (user)
Overtime
Overtime calculation periods and per-employee overtime decisions.
/{pbx_id}/user/{employee_id}/user-overtime-decision/getOvertime
Calculate overtime for an employee over a date range (user)
get
/{pbx_id}/user/{employee_id}/user-overtime-decision
List a specific employee's overtime decisions (user)
post
/{pbx_id}/user/{employee_id}/user-overtime-decision
Create or update an employee's overtime decision (user)
get
/{pbx_id}/user/{employee_id}/user-overtime-decision-preference
Read the employee's overtime decision preference (user)
put
/{pbx_id}/user/{employee_id}/user-overtime-decision-preference
Save the employee's overtime decision preference (user)
delete
/{pbx_id}/user/{employee_id}/user-overtime-decision-preference
Remove the employee's overtime decision preference (user)
get
/{pbx_id}/users-overtime-decisions
List overtime decisions for all employees (user)
get
/{pbx_id}/overtime-calculation-periods
List overtime calculation periods for a tenant (user)
Work times
Weekly and required work times and compiled workshifts.
/{pbx_id}/user/{employee_id}/compiled-user-workshifts
List compiled workshifts for an employee (user)
post
/{pbx_id}/interactive-calendar
Build the interactive calendar for an employee (user)
get
/{pbx_id}/work-times
List weekly work times for employees in the tenant (user)
get
/{pbx_id}/user/{employee_id}/work-times
List weekly work times for a single employee (user)
get
/{pbx_id}/user/{employee_id}/required-work-time
Get daily required work time for a single employee (user)
Schedules
Managed work schedules, slots, and entry assignments.
/{pbx_id}/schedules
List schedules for the tenant (user)
get
/{pbx_id}/schedule-management
List managed schedules for the tenant (user)
post
/{pbx_id}/schedule-management
Create a schedule (user)
get
/{pbx_id}/schedule-management/{schedule}
Get a managed schedule (user)
put
/{pbx_id}/schedule-management/{schedule}
Update a schedule (user)
patch
/{pbx_id}/schedule-management/{schedule}
Partially update a schedule (user)
delete
/{pbx_id}/schedule-management/{schedule}
Delete a schedule (user)
get
/{pbx_id}/schedule-management/{schedule}/employees
List the employees a schedule may assign (user)
get
/{pbx_id}/schedule-management/{schedule}/calendar
Get the weekly calendar for a schedule (user)
get
/{pbx_id}/schedule-management/{schedule}/colors
List employee colors for a schedule (user)
put
/{pbx_id}/schedule-management/{schedule}/colors/{employee}
Set an employee color for a schedule (user)
post
/{pbx_id}/schedule-management/{schedule}/slots
Create a slot in a schedule (user)
put
/{pbx_id}/schedule-management/{schedule}/slots/{slot}
Update a schedule slot (user)
delete
/{pbx_id}/schedule-management/{schedule}/slots/{slot}
Delete a schedule slot (user)
post
/{pbx_id}/schedule-management/slots/{slot}/entries
Create an entry in a slot (user)
post
/{pbx_id}/schedule-management/slots/{slot}/auto-assign
Auto-assign the best employee to a slot (user)
put
/{pbx_id}/schedule-management/entries/{entry}
Update a schedule entry (user)
delete
/{pbx_id}/schedule-management/entries/{entry}
Delete a schedule entry (user)
patch
/{pbx_id}/schedule-management/entries/{entry}/move
Move a schedule entry to a new time (user)
Calendar
Company and per-employee absence, home office, and personal calendars.
Profile
Employee profile, holidays reports, associated companies, and next availability.
/v2/{pbx}/employee/{employee}/profile
Get your own Tempus profile (user)
get
/{pbx_id}/user/{employee_id}/next-availability
Get the next availability date for an employee (user)
get
/{pbx_id}/user/{employee_id}/public-holidays
List public holidays for an employee (user)
get
/{pbx_id}/user/{employee_id}/profile
Get the Tempus profile for an employee (user)
get
/{pbx_id}/user/{employee_id}/travel-time
List an employee's travel time credits
post
/{pbx_id}/user/{employee_id}/travel-time
Credit travel time to a day
get
/{pbx_id}/user/{employee_id}/user-companies
List companies associated with an employee (user)
get
/{pbx_id}/user/{employee_id}/holidays-reports
Get the holidays report for an employee (user)
Employees
Tempus employees, departments, and their time points.
/{pbx_id}/users
List Tempus employees for the tenant (user)
get
/{pbx_id}/groups
List departments for the tenant (user)
get
/{pbx_id}/departments
List departments for the tenant (user)
get
/{pbx_id}/user/{employee_id}/timepoints
List timepoints for an employee (user)
delete
/{pbx_id}/user/{employee_id}/timepoints/{id}
Delete a timepoint for an employee (user)
Validators
Validator scope and validator-facing pending requests and corrections.
/{pbx_id}/validators
List all validators in the tenant
get
/{pbx_id}/validator/employees
Employees the logged-in validator can validate
get
/{pbx_id}/validator/{employee_id}
Validator-scoped employee profile
get
/{pbx_id}/validator/pending-requests
List employees with pending absence and home office requests (user)
get
/{pbx_id}/validator/pending-corrections
List pending time point corrections in the validator scope (user)
get
/{pbx_id}/validator/pending-corrections/{correction_id}/details
Get the time points behind a pending correction (user)
get
/{pbx_id}/user/{employee_id}/validator-permissions
Get the validator permissions for an employee (user)
Deprecated
get
/{pbx_id}/validator/scope
Get the validator scope (employees the authenticated user can validate)
Deprecated
post
/{pbx_id}/validator/change-employee-status
Change a scoped employee's current status as a validator (user)
get
/v2/{pbx}/employee/{employee}/validator
Get an employee's validator role and queue counts (user)
get
/v2/{pbx}/employee/{employee}/pending-requests/absences
List the absence requests waiting on you to decide (user)
get
/v2/{pbx}/employee/{employee}/pending-requests/home-office
List the home office requests waiting on you to decide (user)
get
/v2/{pbx}/employee/{employee}/pending-requests/time-point-corrections
List the time point corrections waiting on you to decide (user)
Tempus terminals and recurring transactions
Tempus endpoints for badge readers and NFC terminals (authenticated with a PBX API-key token carrying the terminals ability) and for managing recurring transactions (PBX API key).
/AndroidNfc/getUser
Get user by NFC badge
post
/AndroidNfc/getUser
Log a terminal NFC event
post
/terminal/{mac_address}/badge
Get tablet session (grid layout format)
get
/TimeLogger/getBadge
Get badge data (TimeLogger)
post
/TimeLogger/getBadge
Submit badge data (TimeLogger)
post
/recurring-transactions/preview-next-run
Preview the next run of a recurring transaction
get
/recurring-transactions
List recurring transactions
post
/recurring-transactions
Create a recurring transaction
get
/recurring-transactions/{id}
Get a recurring transaction
patch
/recurring-transactions/{id}
Update a recurring transaction
delete
/recurring-transactions/{id}
Delete a recurring transaction
post
/recurring-transactions/{id}/pause
Pause a recurring transaction
post
/recurring-transactions/{id}/resume
Resume a recurring transaction
post
/recurring-transactions/{id}/run-now
Run a recurring transaction now
API v2
API v2
API v2 Endpoints
Second-generation endpoints with improved response structures.
Base URL: /api/v2/
CDRs
CDR Utility
CDR Utility Proxy
Forwards authenticated requests to the internal CDRs API. Rate-limited to 120 requests/minute per user.
Base URL: /api/v1/cdrs-utility/