Voxbi Cockpit APIs
All endpoints

Voxbi Cockpit API

OpenAPI 3.2.0 v0.1.0

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 request
  • X-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.

Servers
  • 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
Authentication
  • bearerAuth Bearer token
  • ApiKeyAuth API key in header "Authorization"
  • PbxServerAuth Bearer token
  • PbxApiKey Bearer token
  • IntegrationApiKey Bearer token

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 /login with 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.

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.

Do Not Disturb

Manage Do Not Disturb rules for users and extensions.

Users

PBX users. Each user owns an extension, devices, presence status, and forwarding rules.

post /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.

Groups

Ring groups that dial multiple destinations simultaneously or in sequence.

Pools

Extension pools and their user assignments.

Tags

Free-form labels attached to users, devices, or numbers for filtering and reporting.

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.

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.

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.

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.

Tempus

Absences

Employee absence requests, absence records, and validator decisions on them.

Home office

Home office requests, home office calendars, and validator decisions on them.

Corrections

Time point correction requests and validator decisions on them.

Overtime

Overtime calculation periods and per-employee overtime decisions.

Work times

Weekly and required work times and compiled workshifts.

Schedules

Managed work schedules, slots, and entry assignments.

get /{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.

Employees

Tempus employees, departments, and their time points.

Validators

Validator scope and validator-facing pending requests and corrections.

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).

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/