# Voxbi Cockpit API v0.1.0 · OpenAPI 3.2.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 - `https://cockpit.voxbi.com/api/v1` — The production API server - `https://staging-cockpit.voxbi.com/api/v1` — The staging API server - `https://dev-cockpit.voxbi.com/api/v1` — The development API server ## Authentication - `bearerAuth` — HTTP Bearer - `ApiKeyAuth` — API key in header "Authorization" - `PbxServerAuth` — HTTP Bearer - `PbxApiKey` — HTTP Bearer - `IntegrationApiKey` — HTTP Bearer ## Endpoints ### Authentication Every endpoint uses **bearer token** authentication: send your token in the `Authorization` header on every request: ``` Authorization: Bearer ``` 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. #### POST /login Log in with email and password (public) Authenticates a user with email and password and returns a personal access token used as the Bearer credential on every subsequent request. `operationId: postAuthLogin` **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "email": "string", "password": "string" } ``` **Responses**: - `200` — OK ```json { "message": "string", "data": { "token": "string" } } ``` - `401` — Invalid email or password. - `403` — The user account is disabled. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /me Get the authenticated user (user) Returns the currently authenticated user's profile data including extensions, SIP devices, groups, twinnings, and integrations. Requires a user-owned bearer token. `operationId: getAuthMe` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "message": "string", "data": { "id": "string", "pbx_id": "string", "full_name_with_email": "string", "first_name": "string", "last_name": "string", "email": "string", "language": "string", "access_token": "string?", "email_verified_at": "string?", "status": "string", "allow_telephony": "boolean", "allow_dnd": "boolean", "allow_change_twinning_dest": "boolean", "allow_call_forwarding": "boolean", "allow_manage_global_contacts": "boolean", "call_recordings_visibility": "string?", "extension_roaming": "boolean", "call_information_visibility": "string?", "allow_status_changer": "boolean", "allow_manage_voicemail_parameters": "boolean", "show_in_address_book": "boolean", "voicemail_type": "string?", "voicemail_destination": "string?", "concurrent_calls": "integer?", "vip": "boolean", "sync_source": "string?", "allow_anonymous_calls": "boolean", "identity_provider_uid": "string?", "is_shadow": "boolean", "created_at": "string", "updated_at": "string", "webrtc_configuration": "object?", "extensions": [ [] ], "sipDevices": [ [] ], "groups": [ [] ], "twinnings": [ [] ], "caller_identities": [ [] ], "integrations": [ [] ], "pbx": [], "microsoft": { "fetch_contacts": "boolean" }, "odoo": { "fetch_contacts": "boolean" }, "employee_id": "string?", "tempus": "string?" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. #### GET /user Get the authenticated user record (user) Returns the raw authenticated user model (the owner of the Sanctum token). This is a thin endpoint that serialises the user record directly; for the assembled profile with extensions, SIP devices, groups, twinnings and integrations use `GET /me` instead. Hidden attributes (password, tokens) are never serialised. `operationId: getAuthUserRecord` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "string", "pbx_id": "string", "first_name": "string", "last_name": "string", "email": "string", "status": "string", "created_at": "string?", "updated_at": "string?" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. #### GET /magic-login/{token} Log in with a magic link token Authenticates a user via a magic link token. Returns a redirect or JSON response on success. `operationId: getAuthMagicLogin` **Parameters**: - `Accept` (header, string, optional) - `token` (path, string, required) — The magic link token sent to the user's email. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "message": "string", "data": { "token": "string" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. #### POST /passwordless/login Request Passwordless Login Code Sends a one-time login code to the provided email address. The code expires after a configured timeout. `operationId: postAuthPasswordlessLogin` **Parameters**: - `Accept` (header, string, optional) **Request body** (`application/json`): ```json { "email": "string" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "success": "boolean", "expires_in": "integer" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /passwordless/verify Verify Passwordless Login Code Verifies a one-time login code for the given email and returns an auth token on success. `operationId: postAuthPasswordlessVerify` **Parameters**: - `Accept` (header, string, optional) **Request body** (`application/json`): ```json { "email": "string", "code": "string" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "message": "string", "data": { "token": "string" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /passwordless/resend Resend Passwordless Login Code Resends a one-time login code to the provided email address, subject to a cooldown period. `operationId: postAuthPasswordlessResend` **Parameters**: - `Accept` (header, string, optional) **Request body** (`application/json`): ```json { "email": "string" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "success": "boolean", "expires_in": "integer" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /request-password-reset Request a password reset email Sends a password reset email to the provided address. Requires HPP API key authentication. `operationId: postAuthRequestPasswordReset` **Auth**: ApiKeyAuth **Parameters**: - `Accept` (header, string, optional) **Request body** (`application/json`): ```json { "email": "string" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "message": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /reset-password Reset Password Resets the user's password using a valid reset token. Requires HPP API key authentication. `operationId: postAuthResetPassword` **Auth**: ApiKeyAuth **Parameters**: - `Accept` (header, string, optional) **Request body** (`application/json`): ```json { "token": "string", "password": "string" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "message": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /edit-password Set a new password Changes the authenticated user's password by verifying the old password and setting a new one. Requires HPP API key authentication. `operationId: postAuthEditPassword` **Auth**: ApiKeyAuth **Parameters**: - `Accept` (header, string, optional) **Request body** (`application/json`): ```json { "old_password": "string", "new_password": "string" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "message": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. ### 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. #### GET /ai-configuration Get AI configuration (pbx) Returns the PBX's aggregated, read-only AI configuration: the account-wide global prompt and labels, the classification keyword tree, per-extension and per-group prompts, and the active AI profile and feature flags. Requires a PBX "API key" carrying the `ai-configuration` scope. The PBX is resolved from the token. `operationId: getAiConfiguration` **Auth**: PbxApiKey **Parameters**: - `accept` (header, string, optional) **Responses**: - `200` — OK ```json { "pbx_id": "550e8400-e29b-41d4-a716-446655440000", "ai_profile": "premium", "ai_features": { "summary": true, "transcription": true, "translations": false, "keyword_mapping_to_call": false, "tagging_calls": false, "sentiment_analysis": false }, "global_prompt": "You are the AI assistant for Example Corp. Be concise and polite.", "labels": [ "Sales", "Support", "Billing" ], "keywords": [ { "id": "550e8400-e29b-41d4-a716-446655440010", "name": "Billing", "prompt": "Apply when the caller asks about invoices or payments.", "children": [ [] ] } ], "extension_prompts": [ { "extension_id": "550e8400-e29b-41d4-a716-446655440020", "extension": "101", "prompt": "Greet callers as the reception desk and offer to take a message." } ], "group_prompts": [ { "group_id": "550e8400-e29b-41d4-a716-446655440030", "group": "Support", "prompt": "Prioritise urgent tickets and confirm the caller's contract number." } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — The API key does not carry the `ai-configuration` scope. - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. ### 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). #### GET /caller-identities List Caller Identities for the authenticated user Returns a paginated list of caller identities. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listCallerIdentities` **Parameters**: - `accept` (header, string, optional) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "phone_number_id": "550e8400-e29b-41d4-a716-446655440002", "suffix": "23", "label": "Sales line", "caller_identity_target_type": "App\\Models\\User", "caller_identity_target_id": "550e8400-e29b-41d4-a716-446655440003", "order": 1 } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. #### GET /caller-identities/{id} Get a caller Identity Returns the caller identity identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getCallerIdentity` **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — UUID of the caller identity **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "phone_number_id": "550e8400-e29b-41d4-a716-446655440002", "suffix": "23", "label": "Sales line", "caller_identity_target_type": "App\\Models\\User", "caller_identity_target_id": "550e8400-e29b-41d4-a716-446655440003", "order": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. ### Calls Endpoints for initiating and managing outbound calls. #### POST /calls/new Initiate a new call Places an outbound call on behalf of the authenticated user. ## Minimal request `destination` is the only required field. Everything else is optional: ```json { "destination": "+12125550199" } ``` With nothing else supplied, the call is placed using the user's own configuration: their default caller identity and their default ringing targets as set up in the cockpit. ## Choosing target devices Send `targets` when you want to override which of the user's endpoints should ring. Each flag is independent, so you can combine them (for example ring the desk phone and the twinned mobile at the same time): ```json { "destination": "+12125550199", "targets": { "sip_devices": [], "webrtc": false, "twinning": true, "teams": false } } ``` - `sip_devices`: list of SIP device identifiers to ring. Omit or send `null` to let the PBX pick the user's SIP devices. - `webrtc`: ring the browser softphone. Defaults to `false`. - `twinning`: ring the twinned (mobile) number. Defaults to `false`. - `teams`: ring the Microsoft Teams endpoint. Defaults to `false`. Every boolean flag defaults to `false` when it is not passed, so a `targets` object is only useful if at least one flag is `true` or `sip_devices` is populated. Enabling a target only has an effect if the matching configuration or integration exists for the user: WebRTC requires a WebRTC-enabled account, `twinning` requires a twinning number, and `teams` requires the Teams integration. If the underlying feature is not configured, the PBX simply skips that target and rings whatever remains. ## Caller identity `caller_identity` is optional. Pass the UUID of a caller identity available to the user to present a specific outbound number. When omitted, the user's default caller identity is used. `operationId: postCallNew` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `debugAmiTrace` (query, boolean, optional) — Enable AMI trace for debugging - `autoAnswer` (query, boolean, optional) — Auto-answer the call - `forceDialBack` (query, boolean, optional) — Force dial-back mode - `anonymous` (query, boolean, optional) — Make the call anonymous **Request body** (`application/json`) (required): ```json { "destination": "+12125550199", "caller_identity": "550e8400-e29b-41d4-a716-446655440000", "targets": { "sip_devices": "array?", "webrtc": false, "twinning": false, "teams": false } } ``` **Responses**: - `200` — OK ```json { "status": "string", "message": "string", "data": [] } ``` - `400` — Bad Request - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. - `500` — Internal Server Error ### 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. #### GET /call-flows List Call flow Returns a paginated list of call flows. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listCallFlows` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `name`, `enabled`. Apply several at once with filter[key1]=value1&filter[key2]=value2. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Main inbound flow", "description": "Routes incoming calls to support, then voicemail.", "enabled": true, "version": 7, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /call-flows Create a call flow Create a call flow. Only `name`, `description` and `enabled` are accepted; the PBX is taken from the authenticated token. Call flow steps are not part of this request: create them separately against `/call-flow-steps` once the call flow exists. `operationId: createCallFlow` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "name": "string", "description": "string?", "enabled": "boolean" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `201` — Created ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Main inbound flow", "description": "Routes incoming calls to support, then voicemail.", "enabled": true, "version": 7, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /call-flows/{call_flow} Get a Call flow Returns the call flow identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getCallFlow` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Main inbound flow", "description": "Routes incoming calls to support, then voicemail.", "enabled": true, "version": 7, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### 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. #### GET /call-flow-steps List Call flow step Returns a paginated list of call flow steps. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listCallFlowSteps` **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — The filter key can be any of the following keys: id, pbx_id, call_flow_id, type, options, is_active and order. The filter value can be any string or number. You can also apply multiple filters using `filter[key1]=value1&filter[key2]=value2`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ring_user", "is_active": true, "order": 0, "options": { "duration": 20, "also_ring_dialed_extension": false, "also_ring_everyone_in_the_user_group": false, "dial_mobile_twinnings": false, "missed_calls": true, "music_on_hold": "550e8400-e29b-41d4-a716-446655440010", "users": [ "550e8400-e29b-41d4-a716-446655440011" ], "sip_devices": [ "550e8400-e29b-41d4-a716-446655440012" ], "groups": [ "550e8400-e29b-41d4-a716-446655440013" ], "tags": [ "550e8400-e29b-41d4-a716-446655440014" ], "locations": [ "550e8400-e29b-41d4-a716-446655440015" ], "languages": [ "550e8400-e29b-41d4-a716-446655440016" ], "pools": [ "550e8400-e29b-41d4-a716-446655440017" ], "statuses": [ "550e8400-e29b-41d4-a716-446655440018" ], "pickup_lines": [ "550e8400-e29b-41d4-a716-446655440019" ], "sub_statuses": { "550e8400-e29b-41d4-a716-446655440018": [ "550e8400-e29b-41d4-a716-446655440020" ] } } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ring_external_number", "is_active": true, "order": 1, "options": { "duration": 30, "number": "+12125550100", "music_on_hold": "550e8400-e29b-41d4-a716-446655440010" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "call_flow", "is_active": true, "order": 2, "options": { "call_flow_or_extension": "call_flow", "extension": "550e8400-e29b-41d4-a716-446655440030", "call_flow": "550e8400-e29b-41d4-a716-446655440031", "schedule": "550e8400-e29b-41d4-a716-446655440032" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "go_to_ivr", "is_active": true, "order": 0, "options": { "ivr": "550e8400-e29b-41d4-a716-446655440040" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "enter_queue", "is_active": true, "order": 1, "options": { "duration": 60, "queue": "550e8400-e29b-41d4-a716-446655440050" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "text_to_speech", "is_active": true, "order": 0, "options": { "announcement_type": "tts_message", "sound_file": "550e8400-e29b-41d4-a716-446655440060", "language": "fr", "tts_tag": "greeting_morning", "tts_message": "Welcome to Customer Support." } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "change_ringtone_and_label", "is_active": true, "order": 0, "options": { "ringtone": "alert-ring1", "label": "VIP", "music_on_hold": "550e8400-e29b-41d4-a716-446655440010" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "webhook", "is_active": true, "order": 2, "options": { "url": "https://cockpit.voxbi.com/hooks/call" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "send_to_email", "is_active": true, "order": 3, "options": { "sound_file": "550e8400-e29b-41d4-a716-446655440060", "language": "fr", "email": "support@example.com", "email_user": [ "550e8400-e29b-41d4-a716-446655440011" ], "email_to_called_user": false } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "conference_room", "is_active": true, "order": 0, "options": { "extension": "550e8400-e29b-41d4-a716-446655440030" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ivr_extension", "is_active": true, "order": 0, "options": { "sound_file": "550e8400-e29b-41d4-a716-446655440060", "language": "fr" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "multicast", "is_active": true, "order": 0, "options": { "multicast_group": "paging-floor-1", "multicast_pin": "1234" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ai_assistant", "is_active": true, "order": 0, "options": { "ai_provider": "famulor", "famulor_agent": "550e8400-e29b-41d4-a716-446655440070" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "hang_up", "is_active": true, "order": 4, "options": [] }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "start_recording", "is_active": true, "order": 0, "options": [] }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "answer", "is_active": true, "order": 0, "options": [] } ] ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /call-flow-steps/{id} Get a Call flow step Returns the call flow step identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getCallFlowStep` **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ring_user", "is_active": true, "order": 0, "options": { "duration": 20, "also_ring_dialed_extension": false, "also_ring_everyone_in_the_user_group": false, "dial_mobile_twinnings": false, "missed_calls": true, "music_on_hold": "550e8400-e29b-41d4-a716-446655440010", "users": [ "550e8400-e29b-41d4-a716-446655440011" ], "sip_devices": [ "550e8400-e29b-41d4-a716-446655440012" ], "groups": [ "550e8400-e29b-41d4-a716-446655440013" ], "tags": [ "550e8400-e29b-41d4-a716-446655440014" ], "locations": [ "550e8400-e29b-41d4-a716-446655440015" ], "languages": [ "550e8400-e29b-41d4-a716-446655440016" ], "pools": [ "550e8400-e29b-41d4-a716-446655440017" ], "statuses": [ "550e8400-e29b-41d4-a716-446655440018" ], "pickup_lines": [ "550e8400-e29b-41d4-a716-446655440019" ], "sub_statuses": { "550e8400-e29b-41d4-a716-446655440018": [ "550e8400-e29b-41d4-a716-446655440020" ] } } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ring_external_number", "is_active": true, "order": 1, "options": { "duration": 30, "number": "+12125550100", "music_on_hold": "550e8400-e29b-41d4-a716-446655440010" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "call_flow", "is_active": true, "order": 2, "options": { "call_flow_or_extension": "call_flow", "extension": "550e8400-e29b-41d4-a716-446655440030", "call_flow": "550e8400-e29b-41d4-a716-446655440031", "schedule": "550e8400-e29b-41d4-a716-446655440032" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "go_to_ivr", "is_active": true, "order": 0, "options": { "ivr": "550e8400-e29b-41d4-a716-446655440040" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "enter_queue", "is_active": true, "order": 1, "options": { "duration": 60, "queue": "550e8400-e29b-41d4-a716-446655440050" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "text_to_speech", "is_active": true, "order": 0, "options": { "announcement_type": "tts_message", "sound_file": "550e8400-e29b-41d4-a716-446655440060", "language": "fr", "tts_tag": "greeting_morning", "tts_message": "Welcome to Customer Support." } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "change_ringtone_and_label", "is_active": true, "order": 0, "options": { "ringtone": "alert-ring1", "label": "VIP", "music_on_hold": "550e8400-e29b-41d4-a716-446655440010" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "webhook", "is_active": true, "order": 2, "options": { "url": "https://cockpit.voxbi.com/hooks/call" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "send_to_email", "is_active": true, "order": 3, "options": { "sound_file": "550e8400-e29b-41d4-a716-446655440060", "language": "fr", "email": "support@example.com", "email_user": [ "550e8400-e29b-41d4-a716-446655440011" ], "email_to_called_user": false } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "conference_room", "is_active": true, "order": 0, "options": { "extension": "550e8400-e29b-41d4-a716-446655440030" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ivr_extension", "is_active": true, "order": 0, "options": { "sound_file": "550e8400-e29b-41d4-a716-446655440060", "language": "fr" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "multicast", "is_active": true, "order": 0, "options": { "multicast_group": "paging-floor-1", "multicast_pin": "1234" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "ai_assistant", "is_active": true, "order": 0, "options": { "ai_provider": "famulor", "famulor_agent": "550e8400-e29b-41d4-a716-446655440070" } }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "hang_up", "is_active": true, "order": 4, "options": [] }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "start_recording", "is_active": true, "order": 0, "options": [] }, { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "type": "answer", "is_active": true, "order": 0, "options": [] } ] ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### Contacts Shared address book entries available across the PBX. #### GET /contacts List contact Returns a paginated list of contacts. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listContacts` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `id`, `name1`, `name2`, `email`, `company_name`, `department`, `job_title`, `is_private`, `is_blocked_globally`, `private_owner_id`. Apply several at once with filter[key1]=value1&filter[key2]=value2. - `include` (query, string, optional) — Comma-separated related resources to embed (dot-nested where shown). Allowed: `numbers`, `groups`, `blockedByUsers`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_name": "Acme Corp", "department": "Engineering", "job_title": "Head of Product", "name1": "Jane", "name2": "Smith", "email": "jane.smith@example.com", "notes": "Calls every Monday morning", "vip": false, "numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440010", "phone_number": "+12125550100", "label": "Direct line", "type": "business", "speed_dial": "201", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "is_private": false, "private_owner_id": "550e8400-e29b-41d4-a716-446655440002", "editable": true, "is_favorite": false, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "\u2026", "first_name": "\u2026", "last_name": "\u2026", "email": "\u2026" } ] } ], "is_blocked_globally": false, "blocked_by_users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ], "handling_strategy": { "type": "call_flow", "call_flow_id": "string?", "extension_id": "string?", "user_id": "string?", "sip_device_id": "string?" }, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /contacts Create a contact Create an address-book contact. A contact is either private (owned by `private_owner_id`) or shared with a set of `groups` (the two are mutually exclusive). Phone numbers are sent in the nested `contactPhoneNumbers[]` array. `is_private` is derived from `private_owner_id` server-side and must not be sent. The optional `handling_strategy` defines per-contact inbound routing. `operationId: createContact` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "name1": "string", "name2": "string?", "email": "string?", "company_name": "string?", "department": "string?", "job_title": "string?", "notes": "string?", "private_owner_id": "string?", "groups": [ "string" ], "contactPhoneNumbers": [ { "phone_number": "string", "label": "string?", "type": "string", "speed_dial": "string?" } ], "handling_strategy": "object?" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `201` — Created ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_name": "Acme Corp", "department": "Engineering", "job_title": "Head of Product", "name1": "Jane", "name2": "Smith", "email": "jane.smith@example.com", "notes": "Calls every Monday morning", "vip": false, "numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440010", "phone_number": "+12125550100", "label": "Direct line", "type": "business", "speed_dial": "201", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "is_private": false, "private_owner_id": "550e8400-e29b-41d4-a716-446655440002", "editable": true, "is_favorite": false, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ] } ], "is_blocked_globally": false, "blocked_by_users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ], "handling_strategy": { "type": "call_flow", "call_flow_id": "string?", "extension_id": "string?", "user_id": "string?", "sip_device_id": "string?" }, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /contacts/{contact} Get a Contact Returns the contact identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getContact` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_name": "Acme Corp", "department": "Engineering", "job_title": "Head of Product", "name1": "Jane", "name2": "Smith", "email": "jane.smith@example.com", "notes": "Calls every Monday morning", "vip": false, "numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440010", "phone_number": "+12125550100", "label": "Direct line", "type": "business", "speed_dial": "201", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "is_private": false, "private_owner_id": "550e8400-e29b-41d4-a716-446655440002", "editable": true, "is_favorite": false, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ] } ], "is_blocked_globally": false, "blocked_by_users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ], "handling_strategy": { "type": "call_flow", "call_flow_id": "string?", "extension_id": "string?", "user_id": "string?", "sip_device_id": "string?" }, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. #### PUT /contacts/{contact} Update a contact Update an address-book contact. Same request shape as creation, with `name1` still required. `is_private` is derived from `private_owner_id` server-side. `operationId: updateContact` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Contact identifier **Request body** (`application/json`) (required): ```json { "name1": "string", "name2": "string?", "email": "string?", "company_name": "string?", "department": "string?", "job_title": "string?", "notes": "string?", "private_owner_id": "string?", "groups": [ "string" ], "contactPhoneNumbers": [ { "phone_number": "string", "label": "string?", "type": "string", "speed_dial": "string?" } ], "handling_strategy": "object?" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_name": "Acme Corp", "department": "Engineering", "job_title": "Head of Product", "name1": "Jane", "name2": "Smith", "email": "jane.smith@example.com", "notes": "Calls every Monday morning", "vip": false, "numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440010", "phone_number": "+12125550100", "label": "Direct line", "type": "business", "speed_dial": "201", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "is_private": false, "private_owner_id": "550e8400-e29b-41d4-a716-446655440002", "editable": true, "is_favorite": false, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ] } ], "is_blocked_globally": false, "blocked_by_users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ], "handling_strategy": { "type": "call_flow", "call_flow_id": "string?", "extension_id": "string?", "user_id": "string?", "sip_device_id": "string?" }, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### DELETE /contacts/{contact} Delete a contact Soft-delete a contact. The contact is removed from list responses but can be restored by an administrator. `operationId: deleteContact` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Contact identifier **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `204` — Deleted (no content) - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. #### POST /contacts/{id}/block Block a contact Triggers the action on the targeted contact block. `operationId: postContactBlock` **Parameters**: - `accept` (header, string, optional) - `id` (path, integer, required) — Contact ID **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "status": "string", "message": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. #### POST /contacts/{id}/unblock Unblock a contact Triggers the action on the targeted contact unblock. `operationId: postContactUnblock` **Parameters**: - `accept` (header, string, optional) - `id` (path, integer, required) — Contact ID **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "status": "string", "message": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. #### POST /contacts/favorite Toggle a contact as favorite Creates a new contact favorite. Validation rules and required fields are defined in the request body schema below. `operationId: postContactFavorite` **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "contact_id": 1 } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "status": "string", "is_favorite": "boolean" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /source/{source}/contacts Get contacts from a specific source Returns the contact source contacts identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getContactSourceContacts` **Parameters**: - `accept` (header, string, optional) - `source` (path, string, required) — Source identifier - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `search` (query, string, optional) — Free-text search across the resource's searchable fields. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_name": "Acme Corp", "department": "Engineering", "job_title": "Head of Product", "name1": "Jane", "name2": "Smith", "email": "jane.smith@example.com", "notes": "Calls every Monday morning", "vip": false, "numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440010", "phone_number": "+12125550100", "label": "Direct line", "type": "business", "speed_dial": "201", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "is_private": false, "private_owner_id": "550e8400-e29b-41d4-a716-446655440002", "editable": true, "is_favorite": false, "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "\u2026", "first_name": "\u2026", "last_name": "\u2026", "email": "\u2026" } ] } ], "is_blocked_globally": false, "blocked_by_users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ], "handling_strategy": { "type": "call_flow", "call_flow_id": "string?", "extension_id": "string?", "user_id": "string?", "sip_device_id": "string?" }, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. ### 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. #### GET /contacts/imports List your contact imports (user) Returns a paginated list of the authenticated user's contact imports, newest first. This endpoint accepts a USER token only (not a PBX API key): a user only ever sees their own imports. Use `filter[status]=incomplete` to narrow by lifecycle stage, and `?include=records,errors` to embed row-level detail. `operationId: listContactImports` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Sort field. Prefix with `-` for descending. Allowed: `created_at`, `completed_at`, `status`. Defaults to `-created_at`. - `filter[status]` (query, string, optional) — Filter by exact lifecycle status (e.g. `incomplete`, `completed`). - `include` (query, string, optional) — Comma-separated related detail to embed. Allowed: `records`, `errors`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "incomplete", "file_type": "csv", "records_count": 42, "errors_count": 3, "can_confirm": true, "header_row_position": 1, "sheet_index": "integer?", "delimiter": "string?", "enclosure": "\"", "input_encoding": "UTF-8", "skip_on_error": true, "notify_owner_by_email": false, "webhook_url": "string?", "mappings": [ { "field": "name1", "column": 0, "subfields": [ { "name": "\u2026", "value": "\u2026" } ] } ], "created_at": "2026-01-15T09:30:00Z", "started_at": "2026-01-15T09:31:00Z", "completed_at": "2026-01-15T09:31:45Z", "records": [ { "model_id": "550e8400-e29b-41d4-a716-446655440010", "is_new": true, "was_trashed": false } ], "errors": [ { "row": 7, "attribute": "email", "messages": [ "The email must be a valid email address." ], "row_data": { "name1": "Jane", "email": "not-an-email" } } ] } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. #### POST /contacts/imports Upload a contact import file (user) Uploads a CSV or Excel file and creates an import in the `incomplete` state. The file is only stored at this step: no contacts are created yet. Next, configure parsing via the settings endpoint, map columns via the mapping endpoints, then confirm. Accepts a USER token only. The created import (and every contact it will create) is private to the authenticated user. Send the file as `multipart/form-data` under the `file` key. Accepted types: CSV, XLS, XLSX. Rate limited: at most one import may be created per minute per user. Only successful creates count, so a rejected request (422) never blocks a valid retry. Configuring an existing import is not limited. Notification preferences may be set here or via the settings endpoint. `operationId: createContactImport` **Auth**: bearerAuth **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `201` — Created. The response is the import resource itself (unwrapped, not under a `data` key). Fetch the detected columns next via the mapping-options endpoint. ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "incomplete", "file_type": "csv", "records_count": 42, "errors_count": 3, "can_confirm": true, "header_row_position": 1, "sheet_index": "integer?", "delimiter": "string?", "enclosure": "\"", "input_encoding": "UTF-8", "skip_on_error": true, "notify_owner_by_email": false, "webhook_url": "string?", "mappings": [ { "field": "name1", "column": 0, "subfields": [ { "name": "type", "value": "mobile" } ] } ], "created_at": "2026-01-15T09:30:00Z", "started_at": "2026-01-15T09:31:00Z", "completed_at": "2026-01-15T09:31:45Z", "records": [ { "model_id": "550e8400-e29b-41d4-a716-446655440010", "is_new": true, "was_trashed": false } ], "errors": [ { "row": 7, "attribute": "email", "messages": [ "The email must be a valid email address." ], "row_data": { "name1": "Jane", "email": "not-an-email" } } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. - `429` — Too Many Requests. The rate limit for this action has been exceeded. Retry after the window indicated by the Retry-After header. #### GET /contacts/imports/sample Download a sample import file (user) Downloads a headers-only sample CSV showing the contact fields the import accepts (the same file the Cockpit import wizard offers). Column headers are illustrative only: the import mapping is free-form, so you map your own file's columns onto the target fields regardless of their headers. `operationId: getContactImportSample` **Auth**: bearerAuth **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK. A CSV file download. - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. #### GET /contacts/imports/{id} Get one of your contact imports (user) Returns a single import owned by the authenticated user. Use `?include=records,errors` to embed the imported contacts and any row-level failures. Accepts a USER token only; another user's import returns 404. `operationId: getContactImport` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Import identifier - `include` (query, string, optional) — Comma-separated related detail to embed. Allowed: `records`, `errors`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK. The import resource itself (unwrapped, not under a `data` key). ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "incomplete", "file_type": "csv", "records_count": 42, "errors_count": 3, "can_confirm": true, "header_row_position": 1, "sheet_index": "integer?", "delimiter": "string?", "enclosure": "\"", "input_encoding": "UTF-8", "skip_on_error": true, "notify_owner_by_email": false, "webhook_url": "string?", "mappings": [ { "field": "name1", "column": 0, "subfields": [ { "name": "type", "value": "mobile" } ] } ], "created_at": "2026-01-15T09:30:00Z", "started_at": "2026-01-15T09:31:00Z", "completed_at": "2026-01-15T09:31:45Z", "records": [ { "model_id": "550e8400-e29b-41d4-a716-446655440010", "is_new": true, "was_trashed": false } ], "errors": [ { "row": 7, "attribute": "email", "messages": [ "The email must be a valid email address." ], "row_data": { "name1": "Jane", "email": "not-an-email" } } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. #### DELETE /contacts/imports/{id} Delete one of your contact imports (user) Permanently deletes one of the authenticated user's imports, along with its row-level records, errors, and the stored source file. An import in any status may be deleted; the contacts it already created are NOT removed. Accepts a USER token only; another user's import returns 404. `operationId: deleteContactImport` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Import identifier **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `204` — No Content - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. #### GET /contacts/imports/{id}/settings Get parsing settings for an import (user) Returns the parsing settings that apply to this import's file type, each with its type, default, and current value. The client renders exactly these; CSV imports expose `delimiter`, `enclosure`, and `input_encoding`, while Excel imports expose `sheet_index`. Only an `incomplete` import can be read here (otherwise 409). `operationId: getContactImportSettings` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Import identifier **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json [ { "key": "input_encoding", "type": "string", "default": "UTF-8", "current": "string", "allowed_values": [ "UTF-8", "ISO-8859-1" ] } ] ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. - `409` — Conflict. The import is no longer in a state that allows this action (for example, it has already been submitted for processing). Only an `incomplete` import can be configured or confirmed. #### PUT /contacts/imports/{id}/settings Update parsing settings for an import (user) Updates the parsing settings for an `incomplete` import. Send only the keys you want to change. Only an `incomplete` import can be updated (otherwise 409). `operationId: updateContactImportSettings` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Import identifier **Request body** (`application/json`) (required): ```json { "header_row_position": "integer?", "sheet_index": "integer?", "delimiter": "string?", "enclosure": "string?", "input_encoding": "string?", "skip_on_error": "boolean", "notify_owner_by_email": "boolean", "webhook_url": "string?" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK. The updated import resource (unwrapped). It carries the setting values just set (header_row_position, notify_owner_by_email, ...). ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "incomplete", "file_type": "csv", "records_count": 42, "errors_count": 3, "can_confirm": true, "header_row_position": 1, "sheet_index": "integer?", "delimiter": "string?", "enclosure": "\"", "input_encoding": "UTF-8", "skip_on_error": true, "notify_owner_by_email": false, "webhook_url": "string?", "mappings": [ { "field": "name1", "column": 0, "subfields": [ { "name": "type", "value": "mobile" } ] } ], "created_at": "2026-01-15T09:30:00Z", "started_at": "2026-01-15T09:31:00Z", "completed_at": "2026-01-15T09:31:45Z", "records": [ { "model_id": "550e8400-e29b-41d4-a716-446655440010", "is_new": true, "was_trashed": false } ], "errors": [ { "row": 7, "attribute": "email", "messages": [ "The email must be a valid email address." ], "row_data": { "name1": "Jane", "email": "not-an-email" } } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. - `409` — Conflict. The import is no longer in a state that allows this action (for example, it has already been submitted for processing). Only an `incomplete` import can be configured or confirmed. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /contacts/imports/{id}/mapping-options Get column mapping options for an import (user) Returns everything the client needs to render the mapping step: the detected file columns (each with a stable `id` used as `column` in the mapping payload) and the allow-listed target fields a column may be mapped to. Only these target fields are accepted when saving a mapping: no other model attribute (e.g. `private_owner_id`, `pbx_id`, groups) can be targeted, and nothing is auto-mapped. Only an `incomplete` import can be read here (otherwise 409). `operationId: getContactImportMappingOptions` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Import identifier **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "file_columns": [ { "id": 0, "name": "First name" } ], "target_fields": [ { "field": "name1", "label": "First name", "type": "text", "multiple": true, "subfields": [ { "name": "type", "type": "enum", "options": [ "business", "mobile", "other", "fax" ] } ] } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. - `409` — Conflict. The import is no longer in a state that allows this action (for example, it has already been submitted for processing). Only an `incomplete` import can be configured or confirmed. #### PUT /contacts/imports/{id}/mappings Save the column mapping for an import (user) Saves how the file's columns map onto contact fields. Each entry maps one column (`column` = a `file_columns[].id` from mapping-options) onto one `field`. `field` must be one of the allow-listed target fields; any other value (including `private_owner_id`, `pbx_id`, `is_private`, or a groups column) is rejected with 422, so a client cannot forge a mapping to assign contacts to another user or tenant. A `contactPhoneNumbers` mapping must carry a `type` sub-field. A single-value field may be mapped to at most one column; only fields flagged `multiple: true` (currently `contactPhoneNumbers`) may take several columns, otherwise a duplicate mapping is rejected with 422. Only an `incomplete` import can be mapped (otherwise 409). `operationId: updateContactImportMappings` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Import identifier **Request body** (`application/json`) (required): ```json { "mappings": [ { "field": "name1", "column": 0, "subfields": [ { "name": "type", "value": "mobile" } ] } ] } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK. The updated import resource (unwrapped). ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "incomplete", "file_type": "csv", "records_count": 42, "errors_count": 3, "can_confirm": true, "header_row_position": 1, "sheet_index": "integer?", "delimiter": "string?", "enclosure": "\"", "input_encoding": "UTF-8", "skip_on_error": true, "notify_owner_by_email": false, "webhook_url": "string?", "mappings": [ { "field": "name1", "column": 0, "subfields": [ { "name": "type", "value": "mobile" } ] } ], "created_at": "2026-01-15T09:30:00Z", "started_at": "2026-01-15T09:31:00Z", "completed_at": "2026-01-15T09:31:45Z", "records": [ { "model_id": "550e8400-e29b-41d4-a716-446655440010", "is_new": true, "was_trashed": false } ], "errors": [ { "row": 7, "attribute": "email", "messages": [ "The email must be a valid email address." ], "row_data": { "name1": "Jane", "email": "not-an-email" } } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. - `409` — Conflict. The import is no longer in a state that allows this action (for example, it has already been submitted for processing). Only an `incomplete` import can be configured or confirmed. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /contacts/imports/{id}/confirm Confirm and start an import (user) Confirms an `incomplete` import and queues it for background processing. The import must have a saved mapping (`can_confirm: true`) or a 422 is returned. On success the import moves to `pending` and is processed asynchronously; poll the get-import endpoint for the final status and counts. Only an `incomplete` import can be confirmed (otherwise 409). Imports created in the Cockpit admin are not drivable here, and an import started via this API cannot be completed from the Cockpit admin: the two flows are kept separate. `operationId: postContactImportConfirm` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) — Import identifier **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK. The import resource (unwrapped), now `pending`. ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "incomplete", "file_type": "csv", "records_count": 42, "errors_count": 3, "can_confirm": true, "header_row_position": 1, "sheet_index": "integer?", "delimiter": "string?", "enclosure": "\"", "input_encoding": "UTF-8", "skip_on_error": true, "notify_owner_by_email": false, "webhook_url": "string?", "mappings": [ { "field": "name1", "column": 0, "subfields": [ { "name": "type", "value": "mobile" } ] } ], "created_at": "2026-01-15T09:30:00Z", "started_at": "2026-01-15T09:31:00Z", "completed_at": "2026-01-15T09:31:45Z", "records": [ { "model_id": "550e8400-e29b-41d4-a716-446655440010", "is_new": true, "was_trashed": false } ], "errors": [ { "row": 7, "attribute": "email", "messages": [ "The email must be a valid email address." ], "row_data": { "name1": "Jane", "email": "not-an-email" } } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Data Not Found. This error is returned when the requested data is not found. - `409` — Conflict. The import is no longer in a state that allows this action (for example, it has already been submitted for processing). Only an `incomplete` import can be configured or confirmed. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. ### Extensions Internal dial numbers assigned to users, devices, queues, and other PBX entities. #### GET /extensions List extension Returns a paginated list of extensions. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listExtensions` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `number`, `description`, `assigned_to_type`, `user.show_in_address_book`. Apply several at once with filter[key1]=value1&filter[key2]=value2. - `include` (query, string, optional) — Comma-separated related resources to embed (dot-nested where shown). Allowed: `famulorAgent`, `sipDevice`, `user`, `user.employee`, `user.groups`, `user.callerIdentities`, `user.callerIdentities.phoneNumber`, `user.sipDevices`, `user.twinnings`, `user.queues`, `user.queues.statuses`, `user.locations`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "assigned_to_type": "user", "assigned_to_id": "550e8400-e29b-41d4-a716-446655440002", "external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440004", "number": "1337", "name": "Support line", "description": "Front-line support line", "record_external_calls": true, "record_internal_calls": false, "sync_source": "manual", "full_name_with_extension_number": "Jane Smith (1337)", "assigned_to": [], "employee_id": "550e8400-e29b-41d4-a716-446655440005", "department_id": "550e8400-e29b-41d4-a716-446655440006", "is_favorite": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /extensions/{id} Get an Extension Returns the extension identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getExtension` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "assigned_to_type": "user", "assigned_to_id": "550e8400-e29b-41d4-a716-446655440002", "external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440004", "number": "1337", "name": "Support line", "description": "Front-line support line", "record_external_calls": true, "record_internal_calls": false, "sync_source": "manual", "full_name_with_extension_number": "Jane Smith (1337)", "assigned_to": [], "employee_id": "550e8400-e29b-41d4-a716-446655440005", "department_id": "550e8400-e29b-41d4-a716-446655440006", "is_favorite": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. #### GET /favorite-extensions Get favorite extensions for the authenticated user Returns a paginated list of extension favorites. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: getExtensionFavorites` **Parameters**: - `accept` (header, string, optional) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "integer", "pbx_id": "integer", "extension": "string", "user_id": "integer?", "created_at": "string", "updated_at": "string" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. ### Groups Ring groups that dial multiple destinations simultaneously or in sequence. #### GET /groups List group Returns a paginated list of groups. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listGroups` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `name`, `description`. Apply several at once with filter[key1]=value1&filter[key2]=value2. - `include` (query, string, optional) — Comma-separated related resources to embed (dot-nested where shown). Allowed: `users`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ] } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /groups Create a group Create a group and optionally attach users, group permissions, and pickup-lines / phone numbers. `pbx_id` is forced from the authenticated user. `operationId: createGroup` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "pbx_id": "string", "name": "string", "description": "string?", "defaultInternalCallFlow": "string?", "defaultExternalCallFlow": "string?", "users": [ "string" ], "pickupUsers": [ "string" ], "allowManageGroupContacts": [ "string" ], "allowAccessToGroupContacts": [ "string" ], "phoneNumberAssignations": [ "string" ], "allow_call_pickups": "boolean", "allow_default_pbxes_outgoing_phone_numbers": "boolean", "display_tab_to_everyone_inside_voxbi": "boolean", "callerIdentities": [ { "phoneNumber": "string", "suffix": "string?", "label": "string?" } ] } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `201` — Created ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ] } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /groups/{id} Get a Group Returns the group identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getGroup` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440006", "first_name": "Jane", "last_name": "Smith", "email": "jane.smith@example.com" } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### IVR Interactive Voice Response menus that play a prompt and route the caller based on the key they press. #### GET /ivrs List ivr Returns a paginated list of ivrs. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listIvrs` **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — The filter key can be any of the following keys: id, pbx_id, name and comment. The filter value can be any string or number. You can also apply multiple filters using `filter[key1]=value1&filter[key2]=value2`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Customer Support Menu", "comment": "After-hours routing for the support line", "announcement_id": "550e8400-e29b-41d4-a716-446655440002", "announcement_language": "fr", "steps": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "ivr_id": "550e8400-e29b-41d4-a716-446655440002", "target_type": "App\\Models\\CallFlow", "target_id": "550e8400-e29b-41d4-a716-446655440003", "name": "Sales department", "option": "1", "language": "fr", "voip_ivr_btn_id": 42, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "deleted_at": "string?" } ] } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /ivrs Create an IVR Create an IVR menu. `announcement` is the SoundFile of type `announcement` played when entering the menu; `musicOnHold` is an optional SoundFile of type `music`. `default_action` controls what happens on caller timeout. `operationId: createIvr` **Auth**: bearerAuth **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "pbx_id": "string", "name": "string", "comment": "string?", "announcement": "string", "musicOnHold": "string?", "default_action": "enum" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `201` — Created ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Customer Support Menu", "comment": "After-hours routing for the support line", "announcement_id": "550e8400-e29b-41d4-a716-446655440002", "announcement_language": "fr", "steps": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "ivr_id": "550e8400-e29b-41d4-a716-446655440002", "target_type": "App\\Models\\CallFlow", "target_id": "550e8400-e29b-41d4-a716-446655440003", "name": "Sales department", "option": "1", "language": "fr", "voip_ivr_btn_id": 42, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "deleted_at": "string?" } ] } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /ivrs/{id} Get an IVR Returns the ivr identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getIvr` **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Customer Support Menu", "comment": "After-hours routing for the support line", "announcement_id": "550e8400-e29b-41d4-a716-446655440002", "announcement_language": "fr", "steps": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "ivr_id": "550e8400-e29b-41d4-a716-446655440002", "target_type": "App\\Models\\CallFlow", "target_id": "550e8400-e29b-41d4-a716-446655440003", "name": "Sales department", "option": "1", "language": "fr", "voip_ivr_btn_id": 42, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "deleted_at": "string?" } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### IVR Steps Individual menu options inside an IVR. Each step maps a digit (or timeout) to a destination. #### GET /ivr-steps List IVR step Returns a paginated list of ivr steps. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listIvrSteps` **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — The filter key can be any of the following keys: id, parent_id, ivr_id, sound_file_id, name, option, delay, action_type and action_value. The filter value can be any string or number. You can also apply multiple filters using `filter[key1]=value1&filter[key2]=value2`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "ivr_id": "550e8400-e29b-41d4-a716-446655440002", "target_type": "App\\Models\\CallFlow", "target_id": "550e8400-e29b-41d4-a716-446655440003", "name": "Sales department", "option": "1", "language": "fr", "voip_ivr_btn_id": 42, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "deleted_at": "string?" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /ivr-steps/{id} Get an IVR step Returns the ivr step identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getIvrStep` **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "ivr_id": "550e8400-e29b-41d4-a716-446655440002", "target_type": "App\\Models\\CallFlow", "target_id": "550e8400-e29b-41d4-a716-446655440003", "name": "Sales department", "option": "1", "language": "fr", "voip_ivr_btn_id": 42, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "deleted_at": "string?" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### Languages Languages available for sound files, voice prompts, and user preferences. #### GET /languages List language Returns a paginated list of languages. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listLanguages` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `id`, `name`. Apply several at once with filter[key1]=value1&filter[key2]=value2. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "English", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### POST /languages Create a language Enable a language for the PBX. `name` must be one of the supported locale display names and unique within the PBX. `pbx_id` is forced from the authenticated principal (a user's PBX, or the Pbx-owned API key itself) and is never read from the request body. `operationId: createLanguage` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "name": "string" } ``` **Responses**: - `201` — Created ```json { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "English", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /languages/{id} Get a Language Returns the language identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getLanguage` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "English", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### Locations Physical offices or sites associated with the PBX, used for emergency call routing and reporting. #### GET /locations List location Returns a paginated list of locations. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listLocations` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `name`, `description`. Apply several at once with filter[key1]=value1&filter[key2]=value2. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_id": "550e8400-e29b-41d4-a716-446655440004", "parent_id": "550e8400-e29b-41d4-a716-446655440002", "name": "Luxembourg HQ", "description": "Main office, 5th floor", "street_no": "12", "street": "Main Street", "city": "Luxembourg", "postal": "1234", "country_id": "550e8400-e29b-41d4-a716-446655440003", "lft": 1, "rgt": 10, "depth": 0, "enable_location_as_presence_status": false, "style": { "icon_class": "la-map-pin", "bg_color": "#3490dc", "font_color": "#ffffff" }, "is_fixed_location": true, "latitude": 49.6116, "longitude": 6.1319, "geofence_radius_m": 100, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /locations/{id} Get a Location Returns the location identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getLocation` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_id": "550e8400-e29b-41d4-a716-446655440004", "parent_id": "550e8400-e29b-41d4-a716-446655440002", "name": "Luxembourg HQ", "description": "Main office, 5th floor", "street_no": "12", "street": "Main Street", "city": "Luxembourg", "postal": "1234", "country_id": "550e8400-e29b-41d4-a716-446655440003", "lft": 1, "rgt": 10, "depth": 0, "enable_location_as_presence_status": false, "style": { "icon_class": "la-map-pin", "bg_color": "#3490dc", "font_color": "#ffffff" }, "is_fixed_location": true, "latitude": 49.6116, "longitude": 6.1319, "geofence_radius_m": 100, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### 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. #### GET /numbers List phone numbers on the PBX List the PhoneNumbers attached to the caller's PBX (resolved from the bearer token). Each entry includes the currently-attached call flow (id + summary) when one is configured. The list is **paginated** (`data` + `meta` + `links`) and supports filtering and sorting. `operationId: listPbxNumbers` **Auth**: IntegrationApiKey **Parameters**: - `filter[number]` (query, string, optional) — Filter by phone number (substring match). A leading `+` is ignored, so `filter[number]=+4922` and `filter[number]=4922` both match. - `filter[name]` (query, string, optional) — Filter by the number's name (substring match). - `sort` (query, enum, optional) — Sort field; prefix with `-` for descending. Allowed: `number`, `name`, `created_at`. Defaults to `number` ascending. · enum: number, -number, name, -name, created_at, -created_at - `page` (query, integer, optional) — Page number (1-based). - `per_page` (query, integer, optional) — Items per page. Defaults to and is capped at 100 (the API page-length limit); larger values are clamped to 100. **Responses**: - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "number": "+12125550100", "name": "Customer Support", "is_active": true, "call_flow_id": "550e8400-e29b-41d4-a716-446655440100", "call_flow": { "id": "string", "name": "string", "enabled": "boolean" } } ], "links": [], "meta": [] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. #### PUT /numbers/{id}/call-flow Attach a call flow to a phone number Set the handling strategy of a PhoneNumber to route incoming calls through a specific call flow. Both the PhoneNumber and the CallFlow must belong to the caller's PBX. `operationId: updatePbxNumberCallFlow` **Auth**: IntegrationApiKey **Parameters**: - `id` (path, string, required) — PhoneNumber UUID. **Request body** (`application/json`) (required): ```json { "call_flow_id": "550e8400-e29b-41d4-a716-446655440100" } ``` **Responses**: - `200` — Updated PhoneNumber with the new call flow attached. ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "number": "+12125550100", "name": "Customer Support", "is_active": true, "call_flow_id": "550e8400-e29b-41d4-a716-446655440100", "call_flow": { "id": "string", "name": "string", "enabled": "boolean" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — PhoneNumber not found in the caller's PBX. - `422` — Validation error - call_flow_id missing, malformed, or doesn't belong to the caller's PBX. #### POST /numbers/orders/check Check whether a phone number can be ordered at a given address Pre-flight check that validates an address with the upstream registry and returns (a) the dial `prefix` for the resolved location, (b) the geocoder's `resolvedAddress`, and (c) the `kycRequirements` that must accompany the future order. Call this before `POST /numbers/orders`. ### Comparing the address The address is geocoded, so `resolvedAddress` may differ from what you sent (`address` echoes your input). Compare the two and, if they differ, confirm the corrected values with the end user before placing the order - the order endpoint persists the geocoder-resolved values. Structured fields in `resolvedAddress` are nullable (the geocoder may fail to pin a component such as the street number); `formattedAddress` is always present. ### Working with `kycRequirements` `kycRequirements` lists the KYC documents that must be supplied on `POST /numbers/orders`. Each **top-level entry** is either: * an **object** - that exact document is required, or * an **array of objects** - you must provide **any one** of the documents listed inside (an "OR group"). So the example below requires **two** documents in total: * either a `business_registration_certificate` **or** a `utility_bill` (the OR group), **and** * an `id_document` (the standalone entry). Each `documentType` is the code you reference when uploading on `POST /numbers/orders`: send file documents as a file part `kyc[]` (e.g. `kyc[utility_bill]` carrying `bill.pdf`; accepted MIME types `application/pdf`, `image/jpeg`, `image/png`), and identifier-only documents as a form field `kyc[]=` (e.g. `kyc[business_registration_number]=BE-12345`). The optional `notes` field carries country-specific context (the local name of the document, or a freshness constraint such as "dated within 3 months") and can be surfaced verbatim to the end user. `operationId: checkPhoneNumberOrder` **Auth**: IntegrationApiKey **Request body** (`application/json`) (required): ```json { "street": "Adenauerallee", "street_number": "1", "postal_code": "53113", "city": "Bonn", "area_code": "string?", "country": "DE" } ``` **Responses**: - `200` — Address resolved successfully; KYC requirements returned. ```json { "address": { "street": "Adenauerallee", "street_number": "1", "postal_code": "53113", "city": "Bonn", "country": "DE" }, "resolvedAddress": { "street": "Adenauerallee", "streetNumber": "1", "postalCode": "53113", "city": "Bonn", "country": "DE", "formattedAddress": "Adenauerallee 1, 53113 Bonn, Germany" }, "prefix": "+49228", "kycRequirements": [ [ { "documentType": "utility_bill", "notes": "Dated within 3 months" }, [ { "documentType": "utility_bill", "notes": "Dated within 3 months" } ] ] ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — The address failed validation - locally or upstream (e.g. it could not be resolved, or your account may not order numbers for that country). Same `{ message, errors }` shape as every other API validation 422, with `errors` mapping each rejected field to its messages. No order is created at this stage, so there is no `data`. When an upstream error has no field to attach to, `errors` is an empty object `{}` and `message` carries the reason. #### POST /numbers/orders Place a phone number order Submit a phone number order. Must be called as `multipart/form-data` because KYC document files are part of the request. Call `POST /numbers/orders/check` first to obtain the address-specific `kycRequirements`. You may attach your own `order_id` (any short string, max 64 chars) - it will be echoed back to you in the response, in `GET /numbers/orders/{id}`, and in the asynchronous webhook payload below. If you omit it, the upstream provider will generate one and we'll backfill it on your row. Order fulfilment is asynchronous. This endpoint returns `201` as soon as the order is accepted upstream. The final outcome (success or rejection) will be delivered to your `webhook` URL (if provided) and is queryable via `GET /numbers/orders/{id}`. ### Webhook payload When the order reaches its final state we POST to your `webhook` URL the **exact same body** as `GET /numbers/orders/{id}` (the schema below). Read the `status` field to tell success from rejection: * `status: "success"` - `numbers` and `phone_numbers` are populated. * `status: "error"` - `error_message` carries the rejection reason. `operationId: createPhoneNumberOrder` **Auth**: IntegrationApiKey **Responses**: - `201` — Order accepted upstream and persisted on our side. ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "order_id": "po-2026-00042", "customer_name": "ACME GmbH", "status": "requested", "address": { "street": "Adenauerallee", "street_number": "1", "postal_code": "53113", "city": "Bonn", "area_code": "string?", "country": "DE" }, "formatted_address": "Adenauerallee 1, 53113 Bonn, DE", "quantity": 1, "prefix": "+49228", "numbers": [ "+4922812345678" ], "phone_numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "number": "+12125550100", "name": "Customer Support", "is_active": true, "call_flow_id": "550e8400-e29b-41d4-a716-446655440100", "call_flow": { "id": "string", "name": "string", "enabled": "boolean" } } ], "error_message": "string?", "webhook_url": "string?", "webhook_status": "enum", "webhook_next_retry_at": "string?", "created_at": "string", "updated_at": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Validation failed. `errors` maps each rejected field to its messages. If the order reached the carrier and was rejected there, it is persisted as a retryable `submission_failed` order and returned in `data` (the full order, same shape as `GET /numbers/orders/{id}`); use `data.id` to edit + retry it via `POST /numbers/orders/{id}`. When `data` is absent, no order was created. #### GET /numbers/orders/{id} Get a phone number order Retrieve the current state of a phone number order. The order outcome (assigned numbers on success, or the rejection reason) can be fetched here if you cannot accept the webhook callback, and it also lets you inspect a past order's audit trail. `operationId: getPhoneNumberOrder` **Auth**: IntegrationApiKey **Parameters**: - `id` (path, string, required) — Order UUID returned by `POST /numbers/orders`. **Responses**: - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "order_id": "po-2026-00042", "customer_name": "ACME GmbH", "status": "requested", "address": { "street": "Adenauerallee", "street_number": "1", "postal_code": "53113", "city": "Bonn", "area_code": "string?", "country": "DE" }, "formatted_address": "Adenauerallee 1, 53113 Bonn, DE", "quantity": 1, "prefix": "+49228", "numbers": [ "+4922812345678" ], "phone_numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "number": "+12125550100", "name": "Customer Support", "is_active": true, "call_flow_id": "550e8400-e29b-41d4-a716-446655440100", "call_flow": { "id": "string", "name": "string", "enabled": "boolean" } } ], "error_message": "string?", "webhook_url": "string?", "webhook_status": "enum", "webhook_next_retry_at": "string?", "created_at": "string", "updated_at": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — Order not found in the caller's PBX. #### POST /numbers/orders/{id} Edit and retry a failed phone number order Edit selected fields of a `submission_failed` order and re-submit it upstream. Same multipart contract as `POST /numbers/orders`. Uses `POST` (not `PUT`) on purpose: the body is `multipart/form-data`, and many server runtimes only parse a multipart body when the method is `POST` - on `PUT` the fields and files arrive empty. Send this edit as a plain `POST`. Constraints: - Only orders with status `submission_failed` can be edited. - `country` is frozen. You may re-send it with the same value (handy when you echo back the whole order), but *changing* it returns `422` - order in a different country by creating a new order. Omitting it is also fine. `customer_name` and `order_id` are editable here: send new values to change them, or send an empty `order_id` to clear your reference. If the edited address yields different KYC requirements upstream, the response will be `422` carrying the new requirements; resubmit again with the matching KYC fields. `operationId: updatePhoneNumberOrder` **Auth**: IntegrationApiKey **Parameters**: - `id` (path, string, required) **Responses**: - `200` — Order re-submitted upstream successfully. ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "order_id": "po-2026-00042", "customer_name": "ACME GmbH", "status": "requested", "address": { "street": "Adenauerallee", "street_number": "1", "postal_code": "53113", "city": "Bonn", "area_code": "string?", "country": "DE" }, "formatted_address": "Adenauerallee 1, 53113 Bonn, DE", "quantity": 1, "prefix": "+49228", "numbers": [ "+4922812345678" ], "phone_numbers": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "number": "+12125550100", "name": "Customer Support", "is_active": true, "call_flow_id": "550e8400-e29b-41d4-a716-446655440100", "call_flow": { "id": "string", "name": "string", "enabled": "boolean" } } ], "error_message": "string?", "webhook_url": "string?", "webhook_status": "enum", "webhook_next_retry_at": "string?", "created_at": "string", "updated_at": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — The order was created from a different source (e.g. the Cockpit UI) and cannot be retried via the API. Not field-specific, so the body is just a `message`. - `404` — Order not found in the caller's PBX. - `409` — The order is not in `submission_failed` state, so it cannot be edited or retried. Not field-specific, so the body is just a `message` (the current status is included in it). - `422` — Validation failed. `errors` maps each rejected field to its messages (including an attempt to *change* the locked `country`). If the carrier rejected the retried order, it stays as a retryable `submission_failed` order and is returned in `data` (the full order, same shape as `GET /numbers/orders/{id}`); use `data.id` to edit + retry it via `POST /numbers/orders/{id}`. When `data` is absent, the failure was local validation only. ### 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. #### POST /push-configuration Push the PBX configuration (pbx) Push the authenticated PBX's configuration so that pending changes take effect. This is the programmatic equivalent of the "Push configuration" button in Cockpit, typically called after a number's call flow has been changed. The target PBX is derived from the API key; there is no request body. The presented PBX API key must carry the `push_configuration` ability/scope. **Rate limit:** 1 request per minute per PBX. Exceeding the limit returns `429` with a `Retry-After` header. `operationId: postPushConfiguration` **Auth**: PbxApiKey **Parameters**: - `accept` (header, string, optional) **Responses**: - `200` — Configuration push recorded. ```json { "status": "pushed", "pushed_at": "2026-06-15 09:12:04" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — The presented PBX API key does not carry the required `push_configuration` ability/scope. - `409` — Configuration pushes are currently locked for this PBX. - `429` — Rate limit exceeded (max 1 push per minute per PBX). Wait `Retry-After` seconds before retrying. - `500` — The push could not be recorded; retry later. ### 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. #### POST /odoo-installer/register-install Register an Odoo installation (pbx) Registers (upserts) the Odoo integration for the authenticated PBX and queues the installation job. Consumed by the Voxbi Installer module running inside a customer's Odoo. The PBX is resolved from the API key, so it is never part of the request body. Requires an API key carrying the `odoo-installer` ability. `operationId: postOdooInstallerRegisterInstall` **Auth**: IntegrationApiKey **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`) (required): ```json { "odoo_url": "https://erp.example.com", "odoo_db": "example_prod", "odoo_version": "17.0", "service_user": "svc_voxbi", "service_key": "s3cr3t-service-key", "service_uid": 7, "sync_sip_configurations": true, "is_active": true, "installer_module_version": "1.2.0" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `201` — Created. The integration is registered and the install job is queued. ```json { "integration_id": "string", "status_url": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /odoo-installer/install-status Get the Odoo installation status (pbx) Returns the current install job status for the authenticated PBX's Odoo integration. Requires an API key carrying the `odoo-installer` ability. `operationId: getOdooInstallerInstallStatus` **Auth**: IntegrationApiKey **Parameters**: - `accept` (header, string, optional) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "status": "enum", "results": [ [] ], "updated_at": "string?" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — No Odoo integration exists for the authenticated PBX. #### GET /odoo-installer/get-integration Get the Odoo integration (pbx) Returns the Odoo integration record for the authenticated PBX. The service account API key is never returned. Requires an API key carrying the `odoo-installer` ability. `operationId: getOdooInstallerGetIntegration` **Auth**: IntegrationApiKey **Parameters**: - `accept` (header, string, optional) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "integration_id": "string", "pbx_id": "string", "type": "odoo", "is_active": "boolean", "job_status": "enum", "odoo_url": "string?", "odoo_db": "string?", "service_user": "string?", "odoo_version": "string?", "sync_sip_configurations": "boolean", "updated_at": "string?" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — No Odoo integration exists for the authenticated PBX. #### POST /odoo-installer/update-and-fix-integration Update and re-run the Odoo integration (pbx) Patches the supplied fields on the authenticated PBX's Odoo integration and re-queues the install job (job status is reset to `pending` and previous results are cleared). Every field is optional; only the fields you send are changed. The PBX is resolved from the API key. Requires an API key carrying the `odoo-installer` ability. `operationId: postOdooInstallerUpdateAndFixIntegration` **Auth**: IntegrationApiKey **Parameters**: - `accept` (header, string, optional) **Request body** (`application/json`): ```json { "odoo_url": "https://erp.example.com", "odoo_db": "example_prod", "odoo_version": "17.0", "service_user": "svc_voxbi", "service_key": "s3cr3t-service-key", "service_uid": 7, "sync_sip_configurations": true, "is_active": true, "installer_module_version": "1.2.0" } ``` **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK. The integration was updated and the install job re-queued. ```json { "integration_id": "string", "job_status": "enum", "status_url": "string" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `404` — No Odoo integration exists for the authenticated PBX. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. ### Pbxes The tenant container. Every other resource is scoped to a PBX. #### GET /pbxes List pbxe Returns a paginated list of pbxes. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listPbxes` **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — The filter key can be any of the following keys: id, default_carrier_id, fallback_carrier_id, profile_id, name, comment, reserved_extensions, emergency, automatic_firmware, default_call_pickups_for_new_extensions, phones_default_vlan_pc, phones_default_vlan_phone, phones_web_admin_password, lldp, show_users_first_name_first, allow_changing_record_calls, recordings_destination, oidc_enabled, oidc_allow_sign_up, oidc_email_domain, oidc_client_id, oidc_client_secret, oidc_discover_url, oidc_authorization_url, oidc_token_url, oidc_userinfo_url, oidc_logout_url, oidc_issuer and oidc_identity_fields_mapping. The filter value can be any string or number. You can also apply multiple filters using `filter[key1]=value1&filter[key2]=value2`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "partner_id": "550e8400-e29b-41d4-a716-446655440001", "customer_id": "550e8400-e29b-41d4-a716-446655440002", "default_carrier_id": "550e8400-e29b-41d4-a716-446655440003", "fallback_carrier_id": "550e8400-e29b-41d4-a716-446655440004", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440005", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440006", "no_ext_match_callflow_id": "550e8400-e29b-41d4-a716-446655440007", "profile_id": 42, "name": "Acme Corp", "instance_name": "pbx16dev", "trunk_username": "trunk_acme", "comment": "Migrated from legacy platform in March", "reserved_extensions": "112, 113, 911", "emergency": false, "automatic_firmware": true, "default_call_pickups_for_new_extensions": true, "allow_roaming": true, "phones_default_vlan_pc": 200, "phones_default_vlan_phone": 100, "phones_web_admin_password": "string", "lldp": true, "show_users_first_name_first": true, "capitalize_users_last_name": false, "allow_call_recording": false, "allow_changing_record_calls": false, "recordings_destination": "mixvoip", "recording_start_at": "on_start", "user_provisioning_key": "string", "user_provisioning_ip_addresses": [ "string" ], "it_admin_notification_email": "it@example.com", "impersonation_token": "string", "force_provisioning_sync": "2024-03-01T08:29:07Z", "push_configuration": "2024-03-01T08:29:07Z", "push_contact": "2024-03-01T08:29:07Z", "push_required": false, "push_check_pending": false, "push_check_requested_at": "2024-03-01T08:29:07Z", "push_required_count": 0, "push_other_count": 0, "server_push_date": "2024-03-01T08:29:07Z", "contact_push_date": "2024-03-01T08:29:07Z", "last_config_update": "2024-03-01T08:29:07Z", "tenant_id": "550e8400-e29b-41d4-a716-446655440099", "sso_enabled": false, "sso_type": "openid_connect", "allow_sign_up_with_sso": false, "force_sign_in_with_sso": false, "max_incoming_channels": 50, "max_incoming_channels_sound_file_id": "550e8400-e29b-41d4-a716-446655440008", "music_on_hold_id": "550e8400-e29b-41d4-a716-446655440009", "api_key": "string", "sso_identity_fields_mapping": { "first_name": "given_name", "last_name": "family_name", "email": "email" }, "default_call_ring_duration": 30, "enable_soop_status": true, "ai_profile": "premium", "ai_engine_status": false, "transcript_retention_days": 30, "last_ai_engine_status_activity_check": "2024-03-01T08:29:07Z", "ring_tone": "lu", "show_all_users_in_voxbi": true, "split_internal_external_calls": false, "call_block_logged_out_sip_devices": true, "show_via_in_missed_call": false, "enable_tempus_menu": true, "language": "en", "estimated_users": 25, "estimated_sip_devices": 30, "multicast_sites_ip_addresses": [ "10.10.0.1", "10.10.0.2" ], "flags": { "beta_dashboard": true }, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "deleted_at": "string?" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /pbxes/{id} Get a Pbx Returns the pbx identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getPbx` **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "partner_id": "550e8400-e29b-41d4-a716-446655440001", "customer_id": "550e8400-e29b-41d4-a716-446655440002", "default_carrier_id": "550e8400-e29b-41d4-a716-446655440003", "fallback_carrier_id": "550e8400-e29b-41d4-a716-446655440004", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440005", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440006", "no_ext_match_callflow_id": "550e8400-e29b-41d4-a716-446655440007", "profile_id": 42, "name": "Acme Corp", "instance_name": "pbx16dev", "trunk_username": "trunk_acme", "comment": "Migrated from legacy platform in March", "reserved_extensions": "112, 113, 911", "emergency": false, "automatic_firmware": true, "default_call_pickups_for_new_extensions": true, "allow_roaming": true, "phones_default_vlan_pc": 200, "phones_default_vlan_phone": 100, "phones_web_admin_password": "string", "lldp": true, "show_users_first_name_first": true, "capitalize_users_last_name": false, "allow_call_recording": false, "allow_changing_record_calls": false, "recordings_destination": "mixvoip", "recording_start_at": "on_start", "user_provisioning_key": "string", "user_provisioning_ip_addresses": [ "string" ], "it_admin_notification_email": "it@example.com", "impersonation_token": "string", "force_provisioning_sync": "2024-03-01T08:29:07Z", "push_configuration": "2024-03-01T08:29:07Z", "push_contact": "2024-03-01T08:29:07Z", "push_required": false, "push_check_pending": false, "push_check_requested_at": "2024-03-01T08:29:07Z", "push_required_count": 0, "push_other_count": 0, "server_push_date": "2024-03-01T08:29:07Z", "contact_push_date": "2024-03-01T08:29:07Z", "last_config_update": "2024-03-01T08:29:07Z", "tenant_id": "550e8400-e29b-41d4-a716-446655440099", "sso_enabled": false, "sso_type": "openid_connect", "allow_sign_up_with_sso": false, "force_sign_in_with_sso": false, "max_incoming_channels": 50, "max_incoming_channels_sound_file_id": "550e8400-e29b-41d4-a716-446655440008", "music_on_hold_id": "550e8400-e29b-41d4-a716-446655440009", "api_key": "string", "sso_identity_fields_mapping": { "first_name": "given_name", "last_name": "family_name", "email": "email" }, "default_call_ring_duration": 30, "enable_soop_status": true, "ai_profile": "premium", "ai_engine_status": false, "transcript_retention_days": 30, "last_ai_engine_status_activity_check": "2024-03-01T08:29:07Z", "ring_tone": "lu", "show_all_users_in_voxbi": true, "split_internal_external_calls": false, "call_block_logged_out_sip_devices": true, "show_via_in_missed_call": false, "enable_tempus_menu": true, "language": "en", "estimated_users": 25, "estimated_sip_devices": 30, "multicast_sites_ip_addresses": [ "10.10.0.1", "10.10.0.2" ], "flags": { "beta_dashboard": true }, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "deleted_at": "string?" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### Phone Numbers External DIDs owned by the PBX. Numbers are linked to call flows, users, or queues for inbound routing. #### GET /phone-numbers List Phone number Returns a paginated list of phone numbers. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listPhoneNumbers` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `name`, `number`, `is_active`. Apply several at once with filter[key1]=value1&filter[key2]=value2. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_carrier_id": "550e8400-e29b-41d4-a716-446655440002", "fallback_carrier_id": "550e8400-e29b-41d4-a716-446655440003", "name": "Support line", "language": "fr", "number": "12125550100", "international_prefix": "1", "is_root": true, "is_active": true, "sync_source": "manual", "handling_strategy": { "type": "call_flow", "default_callflow_id": "string?", "no_ext_match_callflow_id": "string?", "prefix_to_remove": "string?", "prefix_to_add": "string?", "call_flow_id": "string?", "extension_id": "string?", "user_id": "string?", "sip_device_id": "string?" }, "number_and_name": "12125550100 (Support line)", "number_without_international_prefix": "2125550100", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /phone-numbers/{id} Find Phone number by ID Returns the phone number identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getPhoneNumber` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_carrier_id": "550e8400-e29b-41d4-a716-446655440002", "fallback_carrier_id": "550e8400-e29b-41d4-a716-446655440003", "name": "Support line", "language": "fr", "number": "12125550100", "international_prefix": "1", "is_root": true, "is_active": true, "sync_source": "manual", "handling_strategy": { "type": "call_flow", "default_callflow_id": "string?", "no_ext_match_callflow_id": "string?", "prefix_to_remove": "string?", "prefix_to_add": "string?", "call_flow_id": "string?", "extension_id": "string?", "user_id": "string?", "sip_device_id": "string?" }, "number_and_name": "12125550100 (Support line)", "number_without_international_prefix": "2125550100", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### Queues Call queues that hold callers until an agent is available, with configurable strategies and music on hold. #### GET /queues List queue Returns a paginated list of queues. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listQueues` **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — The filter key can be any of the following keys: id, pbx_id, pool_id, name, ring_strategy, music_on_hold_id, ring_busy_members, ring_twinnings, ring_duration, interval, wrap_up_time, exit_key, ring_empty, weight, mapping_id, voip_queue_id and call_flow_id. The filter value can be any string or number. You can also apply multiple filters using `filter[key1]=value1&filter[key2]=value2`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Customer Support", "ring_strategy": "ring_all", "ring_busy_members": false, "ring_duration": 20, "interval": 5, "wrap_up_time": 30, "exit_key": "0", "ring_empty": false, "enable_caller_position": false, "caller_position_announce_frequency": 10, "caller_position_language": "en", "music_on_hold": "550e8400-e29b-41d4-a716-446655440004", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "first_name": "Jane", "last_name": "Smith", "name": "Jane Smith", "full_name_with_email": "Jane Smith ", "email": "jane.smith@example.com", "status": "enabled", "type": "user", "language": "en", "sync_source": "manual", "vip": false, "show_in_address_book": true, "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "caller_identity_internal_extension_id": "550e8400-e29b-41d4-a716-446655440002", "caller_identity_external_extension_id": "550e8400-e29b-41d4-a716-446655440003", "allow_telephony": true, "allow_call_forwarding": true, "allow_change_twinning_dest": true, "allow_dnd": true, "allow_status_changer": false, "allow_anonymous_calls": false, "allow_international_calls": false, "allow_eu_calls": true, "allow_national_calls": true, "allow_premium_numbers": false, "allow_sms": false, "allow_manage_global_contacts": false, "allow_manage_voicemail_parameters": true, "allow_in_call_recording": false, "allow_default_pbxes_outgoing_phone_numbers": true, "allow_grafana_access": false, "allow_right_to_disconnect": true, "right_to_disconnect": false, "concurrent_calls": true, "extension_roaming": true, "record_your_calls": false, "record_your_internal_calls": 2, "access_all_call_recordings": false, "call_recordings_visibility": "own_calls_only", "call_information_visibility": "own_calls", "send_missed_call_via_email": true, "limit_email_missed_call_to_direct": false, "show_caller_id_for_twinning_call": 2, "voicemail_type": "internal", "voicemail_destination": "email_only", "invited_at": "string?", "accepted_invitation_at": "string?", "email_verified_at": "2024-02-15T10:00:00Z", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "extensions": [ { "id": "\u2026", "pbx_id": "\u2026", "assigned_to_type": "\u2026", "assigned_to_id": "\u2026", "external_call_flow_id": "\u2026", "internal_call_flow_id": "\u2026", "number": "\u2026", "name": "\u2026", "description": "\u2026", "record_external_calls": "\u2026", "record_internal_calls": "\u2026", "sync_source": "\u2026", "full_name_with_extension_number": "\u2026", "assigned_to": "\u2026", "employee_id": "\u2026", "department_id": "\u2026", "is_favorite": "\u2026", "created_at": "\u2026", "updated_at": "\u2026" } ], "groups": [ { "id": "\u2026", "pbx_id": "\u2026", "default_internal_call_flow_id": "\u2026", "default_external_call_flow_id": "\u2026", "extension_id_shown_outside_the_group": "\u2026", "default_caller_identity_id": "\u2026", "external_uid": "\u2026", "allow_call_pickups": "\u2026", "name": "\u2026", "description": "\u2026", "allow_default_pbxes_outgoing_phone_numbers": "\u2026", "display_tab_to_everyone_inside_voxbi": "\u2026", "created_at": "\u2026", "updated_at": "\u2026", "users": "\u2026" } ], "allow_manage_group_contacts": [ { "id": "\u2026", "pbx_id": "\u2026", "default_internal_call_flow_id": "\u2026", "default_external_call_flow_id": "\u2026", "extension_id_shown_outside_the_group": "\u2026", "default_caller_identity_id": "\u2026", "external_uid": "\u2026", "allow_call_pickups": "\u2026", "name": "\u2026", "description": "\u2026", "allow_default_pbxes_outgoing_phone_numbers": "\u2026", "display_tab_to_everyone_inside_voxbi": "\u2026", "created_at": "\u2026", "updated_at": "\u2026", "users": "\u2026" } ], "allow_access_to_group_contacts": [ { "id": "\u2026", "pbx_id": "\u2026", "default_internal_call_flow_id": "\u2026", "default_external_call_flow_id": "\u2026", "extension_id_shown_outside_the_group": "\u2026", "default_caller_identity_id": "\u2026", "external_uid": "\u2026", "allow_call_pickups": "\u2026", "name": "\u2026", "description": "\u2026", "allow_default_pbxes_outgoing_phone_numbers": "\u2026", "display_tab_to_everyone_inside_voxbi": "\u2026", "created_at": "\u2026", "updated_at": "\u2026", "users": "\u2026" } ], "sip_devices": [ { "id": "\u2026", "pbx_id": "\u2026", "target_type": "\u2026", "target_id": "\u2026", "extension_id_shown_for_internal_calls": "\u2026", "roaming_user_id": "\u2026", "location_id": "\u2026", "parent_sip_device_id": "\u2026", "name": "\u2026", "description": "\u2026", "is_enabled": "\u2026", "ip_internal": "\u2026", "ip_external": "\u2026", "user_agent": "\u2026", "mac": "\u2026", "vlan_phone": "\u2026", "vlan_pc": "\u2026", "sip_username": "\u2026", "alt_username": "\u2026", "transport": "\u2026", "type": "\u2026", "allow_roaming": "\u2026", "language": "\u2026", "easy_deploy": "\u2026", "notify": "\u2026", "allow_default_pbxes_outgoing_phone_numbers": "\u2026", "sync_source": "\u2026", "custom_provisioning": "\u2026", "last_seen": "\u2026", "created_at": "\u2026", "updated_at": "\u2026", "target": "\u2026", "tags": "\u2026", "caller_identities": "\u2026", "location": "\u2026" } ], "twinnings": [ { "id": "\u2026", "user_id": "\u2026", "status": "\u2026", "phone_number": "\u2026", "delay": "\u2026", "sync_source": "\u2026", "type": "\u2026", "dial_strategy": "\u2026", "fmc_enabled": "\u2026", "backup_phone_number": "\u2026", "created_at": "\u2026", "updated_at": "\u2026" } ], "caller_identities": [ [] ], "locations": [ { "id": "\u2026", "pbx_id": "\u2026", "company_id": "\u2026", "parent_id": "\u2026", "name": "\u2026", "description": "\u2026", "street_no": "\u2026", "street": "\u2026", "city": "\u2026", "postal": "\u2026", "country_id": "\u2026", "lft": "\u2026", "rgt": "\u2026", "depth": "\u2026", "enable_location_as_presence_status": "\u2026", "style": "\u2026", "is_fixed_location": "\u2026", "latitude": "\u2026", "longitude": "\u2026", "geofence_radius_m": "\u2026", "created_at": "\u2026", "updated_at": "\u2026" } ], "languages": [ { "id": "\u2026", "pbx_id": "\u2026", "name": "\u2026", "created_at": "\u2026", "updated_at": "\u2026" } ], "tags": [ { "id": "\u2026", "pbx_id": "\u2026", "name": "\u2026", "description": "\u2026", "created_at": "\u2026", "updated_at": "\u2026" } ], "queues": [ [] ] } ] } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /queues/{id} Get a Queue Returns the queue identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getQueue` **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Customer Support", "ring_strategy": "ring_all", "ring_busy_members": false, "ring_duration": 20, "interval": 5, "wrap_up_time": 30, "exit_key": "0", "ring_empty": false, "enable_caller_position": false, "caller_position_announce_frequency": 10, "caller_position_language": "en", "music_on_hold": "550e8400-e29b-41d4-a716-446655440004", "users": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "first_name": "Jane", "last_name": "Smith", "name": "Jane Smith", "full_name_with_email": "Jane Smith ", "email": "jane.smith@example.com", "status": "enabled", "type": "user", "language": "en", "sync_source": "manual", "vip": false, "show_in_address_book": true, "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "caller_identity_internal_extension_id": "550e8400-e29b-41d4-a716-446655440002", "caller_identity_external_extension_id": "550e8400-e29b-41d4-a716-446655440003", "allow_telephony": true, "allow_call_forwarding": true, "allow_change_twinning_dest": true, "allow_dnd": true, "allow_status_changer": false, "allow_anonymous_calls": false, "allow_international_calls": false, "allow_eu_calls": true, "allow_national_calls": true, "allow_premium_numbers": false, "allow_sms": false, "allow_manage_global_contacts": false, "allow_manage_voicemail_parameters": true, "allow_in_call_recording": false, "allow_default_pbxes_outgoing_phone_numbers": true, "allow_grafana_access": false, "allow_right_to_disconnect": true, "right_to_disconnect": false, "concurrent_calls": true, "extension_roaming": true, "record_your_calls": false, "record_your_internal_calls": 2, "access_all_call_recordings": false, "call_recordings_visibility": "own_calls_only", "call_information_visibility": "own_calls", "send_missed_call_via_email": true, "limit_email_missed_call_to_direct": false, "show_caller_id_for_twinning_call": 2, "voicemail_type": "internal", "voicemail_destination": "email_only", "invited_at": "string?", "accepted_invitation_at": "string?", "email_verified_at": "2024-02-15T10:00:00Z", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "extensions": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "assigned_to_type": "user", "assigned_to_id": "550e8400-e29b-41d4-a716-446655440002", "external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440004", "number": "1337", "name": "Support line", "description": "Front-line support line", "record_external_calls": true, "record_internal_calls": false, "sync_source": "manual", "full_name_with_extension_number": "Jane Smith (1337)", "assigned_to": [], "employee_id": "550e8400-e29b-41d4-a716-446655440005", "department_id": "550e8400-e29b-41d4-a716-446655440006", "is_favorite": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "groups": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "\u2026", "first_name": "\u2026", "last_name": "\u2026", "email": "\u2026" } ] } ], "allow_manage_group_contacts": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "\u2026", "first_name": "\u2026", "last_name": "\u2026", "email": "\u2026" } ] } ], "allow_access_to_group_contacts": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "default_internal_call_flow_id": "550e8400-e29b-41d4-a716-446655440002", "default_external_call_flow_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_outside_the_group": "550e8400-e29b-41d4-a716-446655440005", "default_caller_identity_id": "550e8400-e29b-41d4-a716-446655440004", "external_uid": "grp-support", "allow_call_pickups": true, "name": "Support team", "description": "First-line support", "allow_default_pbxes_outgoing_phone_numbers": false, "display_tab_to_everyone_inside_voxbi": false, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "users": [ { "id": "\u2026", "first_name": "\u2026", "last_name": "\u2026", "email": "\u2026" } ] } ], "sip_devices": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "target_type": "user", "target_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_for_internal_calls": "string?", "roaming_user_id": "string?", "location_id": "550e8400-e29b-41d4-a716-446655440002", "parent_sip_device_id": "string?", "name": "Reception desk phone", "description": "Front-desk Yealink T46U", "is_enabled": true, "ip_internal": "192.168.1.42", "ip_external": "203.0.113.10", "user_agent": "Yealink SIP-T46U 108.86.0.10", "mac": "00:0a:95:9d:68:16", "vlan_phone": 100, "vlan_pc": 200, "sip_username": "device_001", "alt_username": "string?", "transport": "tls", "type": "auto", "allow_roaming": false, "language": "en", "easy_deploy": "string?", "notify": "string?", "allow_default_pbxes_outgoing_phone_numbers": false, "sync_source": "provision", "custom_provisioning": "string?", "last_seen": "2024-03-01T08:29:07Z", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "target": [], "tags": [ { "id": "\u2026", "pbx_id": "\u2026", "name": "\u2026", "description": "\u2026", "created_at": "\u2026", "updated_at": "\u2026" } ], "caller_identities": [ [] ], "location": { "id": "\u2026", "pbx_id": "\u2026", "company_id": "\u2026", "parent_id": "\u2026", "name": "\u2026", "description": "\u2026", "street_no": "\u2026", "street": "\u2026", "city": "\u2026", "postal": "\u2026", "country_id": "\u2026", "lft": "\u2026", "rgt": "\u2026", "depth": "\u2026", "enable_location_as_presence_status": "\u2026", "style": "\u2026", "is_fixed_location": "\u2026", "latitude": "\u2026", "longitude": "\u2026", "geofence_radius_m": "\u2026", "created_at": "\u2026", "updated_at": "\u2026" } } ], "twinnings": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "user_id": "550e8400-e29b-41d4-a716-446655440001", "status": "enabled", "phone_number": "+12125550100", "delay": 5, "sync_source": "manual", "type": "mobile", "dial_strategy": "voip_and_gsm_fallback", "fmc_enabled": false, "backup_phone_number": "+12125550101", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "caller_identities": [ [] ], "locations": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_id": "550e8400-e29b-41d4-a716-446655440004", "parent_id": "550e8400-e29b-41d4-a716-446655440002", "name": "Luxembourg HQ", "description": "Main office, 5th floor", "street_no": "12", "street": "Main Street", "city": "Luxembourg", "postal": "1234", "country_id": "550e8400-e29b-41d4-a716-446655440003", "lft": 1, "rgt": 10, "depth": 0, "enable_location_as_presence_status": false, "style": { "icon_class": "la-map-pin", "bg_color": "#3490dc", "font_color": "#ffffff" }, "is_fixed_location": true, "latitude": 49.6116, "longitude": 6.1319, "geofence_radius_m": 100, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "languages": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "English", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "VIP Customers", "description": "Customers with priority routing and dedicated agents.", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "queues": [ [] ] } ] } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### SIP Carriers Upstream SIP trunks used for outbound calls and number termination. #### GET /sip-carriers List SIP carrier Returns a paginated list of sip carriers. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listSipCarriers` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `name`, `sip_user`, `sip_registrar`. Apply several at once with filter[key1]=value1&filter[key2]=value2. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Primary carrier", "sip_user": "trunk_user", "sip_registrar": "sip.carrier.example.com", "register": true, "destination_header": "default", "incoming_header": "request-uri", "dtmf_mode": "rfc4733", "display_name": "Primary carrier (sip.carrier.example.com)", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /sip-carriers/{id} Get a sIP Carrier Returns the sip carrier identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getSipCarrier` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "Primary carrier", "sip_user": "trunk_user", "sip_registrar": "sip.carrier.example.com", "register": true, "destination_header": "default", "incoming_header": "request-uri", "dtmf_mode": "rfc4733", "display_name": "Primary carrier (sip.carrier.example.com)", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. ### SIP Devices Physical or soft SIP endpoints (deskphones, softphones, ATAs) registered against the PBX. #### GET /sip-devices List SIP device Returns a paginated list of sip devices. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listSipDevices` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `name`, `mac`, `sip_username`, `is_enabled`, `user_id`. Apply several at once with filter[key1]=value1&filter[key2]=value2. - `include` (query, string, optional) — Comma-separated related resources to embed (dot-nested where shown). Allowed: `target`, `tags`, `callerIdentities`, `location`. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "target_type": "user", "target_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_for_internal_calls": "string?", "roaming_user_id": "string?", "location_id": "550e8400-e29b-41d4-a716-446655440002", "parent_sip_device_id": "string?", "name": "Reception desk phone", "description": "Front-desk Yealink T46U", "is_enabled": true, "ip_internal": "192.168.1.42", "ip_external": "203.0.113.10", "user_agent": "Yealink SIP-T46U 108.86.0.10", "mac": "00:0a:95:9d:68:16", "vlan_phone": 100, "vlan_pc": 200, "sip_username": "device_001", "alt_username": "string?", "transport": "tls", "type": "auto", "allow_roaming": false, "language": "en", "easy_deploy": "string?", "notify": "string?", "allow_default_pbxes_outgoing_phone_numbers": false, "sync_source": "provision", "custom_provisioning": "string?", "last_seen": "2024-03-01T08:29:07Z", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "target": [], "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "VIP Customers", "description": "Customers with priority routing and dedicated agents.", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "caller_identities": [ [] ], "location": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_id": "550e8400-e29b-41d4-a716-446655440004", "parent_id": "550e8400-e29b-41d4-a716-446655440002", "name": "Luxembourg HQ", "description": "Main office, 5th floor", "street_no": "12", "street": "Main Street", "city": "Luxembourg", "postal": "1234", "country_id": "550e8400-e29b-41d4-a716-446655440003", "lft": 1, "rgt": 10, "depth": 0, "enable_location_as_presence_status": false, "style": { "icon_class": "la-map-pin", "bg_color": "#3490dc", "font_color": "#ffffff" }, "is_fixed_location": true, "latitude": 49.6116, "longitude": 6.1319, "geofence_radius_m": 100, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /sip-devices/{sip_device} Get a sIP device Returns the sip device identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getSipDevice` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "target_type": "user", "target_id": "550e8400-e29b-41d4-a716-446655440003", "extension_id_shown_for_internal_calls": "string?", "roaming_user_id": "string?", "location_id": "550e8400-e29b-41d4-a716-446655440002", "parent_sip_device_id": "string?", "name": "Reception desk phone", "description": "Front-desk Yealink T46U", "is_enabled": true, "ip_internal": "192.168.1.42", "ip_external": "203.0.113.10", "user_agent": "Yealink SIP-T46U 108.86.0.10", "mac": "00:0a:95:9d:68:16", "vlan_phone": 100, "vlan_pc": 200, "sip_username": "device_001", "alt_username": "string?", "transport": "tls", "type": "auto", "allow_roaming": false, "language": "en", "easy_deploy": "string?", "notify": "string?", "allow_default_pbxes_outgoing_phone_numbers": false, "sync_source": "provision", "custom_provisioning": "string?", "last_seen": "2024-03-01T08:29:07Z", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z", "target": [], "tags": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "name": "VIP Customers", "description": "Customers with priority routing and dedicated agents.", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "caller_identities": [ [] ], "location": { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "company_id": "550e8400-e29b-41d4-a716-446655440004", "parent_id": "550e8400-e29b-41d4-a716-446655440002", "name": "Luxembourg HQ", "description": "Main office, 5th floor", "street_no": "12", "street": "Main Street", "city": "Luxembourg", "postal": "1234", "country_id": "550e8400-e29b-41d4-a716-446655440003", "lft": 1, "rgt": 10, "depth": 0, "enable_location_as_presence_status": false, "style": { "icon_class": "la-map-pin", "bg_color": "#3490dc", "font_color": "#ffffff" }, "is_fixed_location": true, "latitude": 49.6116, "longitude": 6.1319, "geofence_radius_m": 100, "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. #### GET /sip-devices/inventory Get SIP device inventory Returns a paginated list of sip device inventory. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: getSipDeviceInventory` **Parameters**: - `accept` (header, string, optional) - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `search` (query, string, optional) — Free-text search across the resource's searchable fields. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "integer", "pbx_id": "integer", "mac_address": "string", "model": "string?", "vendor": "string?", "status": "string", "created_at": "string", "updated_at": "string" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. ### Sound Files Audio files used for greetings, prompts, music on hold, and voicemail. #### GET /sound-files List Sound file Returns a paginated list of sound files. Use the standard `search`, `sort`, `page`, and `perPage` query parameters; use `filter[key]=value` to narrow the result set. Multi-tenant scoping is enforced. `operationId: listSoundFiles` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `search` (query, string, optional) — Free-text search across the resource's searchable fields. - `page` (query, integer, optional) — Page number to fetch. Defaults to `1`. - `per_page` (query, integer, optional) — Number of items per page. Defaults to `25`, maximum `100`. - `sort` (query, string, optional) — Field to sort by. Prefix with `-` for descending order (e.g. `-created_at`). - `filter[key]` (query, string, optional) — Filter the list by one or more fields. Allowed keys: `name`, `comment`, `type`, `source`. Apply several at once with filter[key1]=value1&filter[key2]=value2. **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "parent_id": "550e8400-e29b-41d4-a716-446655440002", "name": "Welcome announcement", "comment": "Played at the start of the main IVR", "message": "Welcome to Customer Support. Press 1 for sales, 2 for support.", "ai_voice_id": "voice_en_us_female_1", "voice_settings": { "stability": 0.75, "similarity_boost": 0.5 }, "source": "uploaded_file", "type": "announcement", "language": "en", "audio_url": "https://api.example.com/sound-files/550e8400-e29b-41d4-a716-446655440000/audio?signature=abc123&expires=1709280000", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ], "links": { "first": "http://localhost/api/v1/resources?page=1", "last": "http://localhost/api/v1/resources?page=1", "prev": "string?", "next": "string?" }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": "http://localhost/api/v1/resources?page=1", "label": "first", "active": true } ], "path": "http://localhost/api/v1/resources", "per_page": 15, "to": 1, "total": 1 } } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `422` — Unprocessable Parameters. This error is returned when a parameter is not valid. #### GET /sound-files/{soundFile} Get a sound File Returns the sound file identified by the path parameter. Multi-tenant scoping is enforced: the caller can only fetch resources within their own PBX. `operationId: getSoundFile` **Auth**: bearerAuth, IntegrationApiKey **Parameters**: - `accept` (header, string, optional) - `id` (path, string, required) **Responses**: - `5XX` — Server error. An unexpected condition was encountered on the server and the request could not be completed. The body is a generic JSON envelope with a `message` field. The response is logged on the server side; quote the request URL + timestamp when reporting an issue. - `200` — OK ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "pbx_id": "550e8400-e29b-41d4-a716-446655440001", "parent_id": "550e8400-e29b-41d4-a716-446655440002", "name": "Welcome announcement", "comment": "Played at the start of the main IVR", "message": "Welcome to Customer Support. Press 1 for sales, 2 for support.", "ai_voice_id": "voice_en_us_female_1", "voice_settings": { "stability": 0.75, "similarity_boost": 0.5 }, "source": "uploaded_file", "type": "announcement", "language": "en", "audio_url": "https://api.example.com/sound-files/550e8400-e29b-41d4-a716-446655440000/audio?signature=abc123&expires=1709280000", "created_at": "2024-03-01T08:29:07Z", "updated_at": "2024-03-01T08:29:07Z" } ``` - `401` — Authorization Token Missing. This error is returned when the authorization token is missing. - `403` — Data Not Found. This error is returned when the requested data is not found. #### GET /sound-files/{soundFile}/audio Stream a sound file's audio (user, pbx) Stream the raw audio bytes of a sound file. The response is sent inline (not as an attachment) so it can be played directly, for example as the `src` of an HTML `