API Docs
Voxbi Cockpit APIs
All endpoints

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:

{ "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):

{
  "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.

HTTP: bearerAuth

User bearer token. Default authentication for customer-facing endpoints. Obtain a token by calling POST /login with your credentials, then send it on every subsequent request as Authorization: Bearer <token>. The token inherits the permissions and PBX scope of the authenticated user.

HTTP Authorization Scheme
bearer
Bearer format
Bearer <token>
debugAmiTrace query · boolean
Enable AMI trace for debugging
autoAnswer query · boolean
Auto-answer the call
forceDialBack query · boolean
Force dial-back mode
anonymous query · boolean
Make the call anonymous
accept header · string
example: application/json

Request body · required

Request schema
destination*string
The number or extension to dial. This is the only required field: a request carrying nothing but `destination` places a valid call.
example: +12125550199
caller_identitystring · uuid
Optional. UUID of the caller identity (root number or identity) to present for this call. Pass it only when this call should go out with a different identity than usual. When omitted, the user's default caller identity is used.
example: 550e8400-e29b-41d4-a716-446655440000
targetsobject
Optional. Overrides which of the user's endpoints ring. Omit the whole object to use the user's configured targets. Every boolean defaults to `false` when not passed, so at least one flag should be `true` (or `sip_devices` populated) for a `targets` object to be meaningful. A flag only takes effect when the matching configuration or integration exists for the user; otherwise the PBX skips that target.
sip_devicesarray<string>
SIP device identifiers to ring. Omit or send `null` to let the PBX resolve the user's SIP devices.
[]string
webrtcboolean
Ring the browser softphone. Defaults to `false`.
example:
twinningboolean
Ring the twinned (mobile) number. Defaults to `false`.
example:
teamsboolean
Ring the Microsoft Teams endpoint. Defaults to `false`.
example:

Responses

Response schema
statusstring
messagestring
dataobject
Free-form object
Response schema
statusstring
messagestring
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
Unprocessable Parameters. This error is returned when a parameter is not valid.
Response schema
messagestring
example: The given data was invalid.
errorsobject
filterarray<string>
[]string
sortarray<string>
[]string
pagearray<string>
[]string
per_pagearray<string>
[]string
Response schema
statusstring
messagestring
post https://cockpit.voxbi.com/api/v1/calls/new
Base URL
Request sample 
curl -X POST 'https://cockpit.voxbi.com/api/v1/calls/new' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"destination":"+12125550199"}'
const response = await fetch('https://cockpit.voxbi.com/api/v1/calls/new', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "destination": "+12125550199"
}),
});

const data = await response.json();
console.log(data);
import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/calls/new',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "destination": "+12125550199"
}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'POST',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"destination\": \"+12125550199\"
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/calls/new', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
{ … }
"destination": "+12125550199"
}
{ … }
"status": "success",
"message": "Call initiated successfully.",
"data": { … }
"call_id": "abc123",
"destination": "+12125550199"
}
}
Host string
example: cockpit.voxbi.com
Date string
example: Mon, 16 Oct 2023 14:08:48 GMT
Connection string
example: close
Cache-Control string
example: no-cache, private
Content-Type string
example: application/json
X-RateLimit-Limit integer
example: 60
X-RateLimit-Remaining integer
example: 59
Vary string
example: Origin
{ … }
"status": "error",
"message": "User PBX instance not found."
}
{ … }
"error": "Authorization Token is missing"
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"errors": { … }
"filter": [ … ],
"The filter field must be an array."
],
"sort": [ … ],
"The sort field must be a string."
],
"page": [ … ],
"The page field must be an integer."
],
"per_page": [ … ]
"The per page field must be an integer."
]
}
}
Cache-Control string
example: private, must-revalidate
Connection string
example: keep-alive
Content-Type string
example: application/json
Vary string
example: Origin
X-RateLimit-Limit integer
Max requests allowed in the current rate-limit window.
example: 60
X-RateLimit-Remaining integer
Requests remaining in the current rate-limit window.
example: 57
{ … }
"status": "error",
"message": "Failed to initiate call."
}