POST /groups — Voxbi Cockpit APIs

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.

HTTP: bearerAuth

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

HTTP Authorization Scheme: bearer
Bearer format: Bearer <token>

accept header · string

example: application/json

Request body · required

Request schema

pbx_id*string · uuid

Pbx identifier (tenant). Must match the authenticated user's PBX.

name*string

length: 3–64

descriptionstring | null

length: 3–255

defaultInternalCallFlowstring | null · uuid

defaultExternalCallFlowstring | null · uuid

usersarray<string>

Member user identifiers

[]string · uuid

pickupUsersarray<string>

Users allowed to pick up calls in this group

[]string · uuid

allowManageGroupContactsarray<string>

Users allowed to manage this group's contacts

[]string · uuid

allowAccessToGroupContactsarray<string>

Users allowed to view this group's contacts

[]string · uuid

phoneNumberAssignationsarray<string>

Phone numbers attached to the group

[]string · uuid

allow_call_pickupsboolean

Whether group members may pick up each others' ringing calls

allow_default_pbxes_outgoing_phone_numbersboolean

Whether the PBX-default outbound numbers are usable from this group

display_tab_to_everyone_inside_voxbiboolean

Whether the group's tab is visible to all PBX users in Voxbi

callerIdentitiesarray<object>

Outbound caller identities exposed to the group

phoneNumber*string · uuid

suffixstring | null

pattern: ^\d{0,5}\*?$

labelstring | null

length: 0–255

Responses

Response schema

dataobject

Group of users that share routing defaults and (optionally) a common caller identity. Many fields are foreign keys pointing at defaults used when the group's users place or receive calls.

id*string · uuid

Group identifier

read-only

example: 550e8400-e29b-41d4-a716-446655440000

pbx_id*string · uuid

Pbx identifier (tenant)

example: 550e8400-e29b-41d4-a716-446655440001

default_internal_call_flow_idstring | null · uuid

Call flow used for internal calls reaching this group

example: 550e8400-e29b-41d4-a716-446655440002

default_external_call_flow_idstring | null · uuid

Call flow used for external calls reaching this group

example: 550e8400-e29b-41d4-a716-446655440003

extension_id_shown_outside_the_groupstring | null · uuid

Extension displayed to non-group members

example: 550e8400-e29b-41d4-a716-446655440005

default_caller_identity_idstring | null · uuid

Default caller identity applied to the group's outbound calls

example: 550e8400-e29b-41d4-a716-446655440004

external_uidstring | null

External identifier from a CRM or directory sync

example: grp-support

allow_call_pickupsboolean

Whether group members may pick up each others' ringing calls

example: 1

name*string

length: 0–64

example: Support team

descriptionstring | null

length: 0–255

example: First-line support

allow_default_pbxes_outgoing_phone_numbersboolean

Whether the group's CIDs include the PBX-default outbound numbers

example:

display_tab_to_everyone_inside_voxbiboolean

Whether the group's tab is shown to everyone in the PBX

example:

created_atstring | null · date-time

read-only

example: 2024-03-01T08:29:07Z

updated_atstring | null · date-time

read-only

example: 2024-03-01T08:29:07Z

usersarray<object>

Members of the group, each as a user reference. Returned only when requested via `?include=users`.

idstring · uuid

read-only

example: 550e8400-e29b-41d4-a716-446655440006

first_namestring | null

example: Jane

last_namestring | null

example: Smith

emailstring | null · email

example: jane.smith@example.com

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

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.

Response schema

messagestring

exceptionstring

Only present in non-production environments.

filestring

Only present in non-production environments.

lineinteger

Only present in non-production environments.

post https://cockpit.voxbi.com/api/v1/groups

Base URL

Request sample

curl -X POST 'https://cockpit.voxbi.com/api/v1/groups' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"pbx_id":"550e8400-e29b-41d4-a716-446655440001","name":"Customer Support","description":"First-line support team","users":["550e8400-e29b-41d4-a716-446655440010","550e8400-e29b-41d4-a716-446655440011"],"allow_call_pickups":true,"allow_default_pbxes_outgoing_phone_numbers":false,"display_tab_to_everyone_inside_voxbi":false,"callerIdentities":[{"phoneNumber":"550e8400-e29b-41d4-a716-446655440020","suffix":"23","label":"Support line"}]}'

const response = await fetch('https://cockpit.voxbi.com/api/v1/groups', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "pbx_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Customer Support",
    "description": "First-line support team",
    "users": [
        "550e8400-e29b-41d4-a716-446655440010",
        "550e8400-e29b-41d4-a716-446655440011"
    ],
    "allow_call_pickups": true,
    "allow_default_pbxes_outgoing_phone_numbers": false,
    "display_tab_to_everyone_inside_voxbi": false,
    "callerIdentities": [
        {
            "phoneNumber": "550e8400-e29b-41d4-a716-446655440020",
            "suffix": "23",
            "label": "Support line"
        }
    ]
}),
});

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

import requests

response = requests.post('https://cockpit.voxbi.com/api/v1/groups',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "pbx_id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Customer Support",
    "description": "First-line support team",
    "users": [
        "550e8400-e29b-41d4-a716-446655440010",
        "550e8400-e29b-41d4-a716-446655440011"
    ],
    "allow_call_pickups": true,
    "allow_default_pbxes_outgoing_phone_numbers": false,
    "display_tab_to_everyone_inside_voxbi": false,
    "callerIdentities": [
        {
            "phoneNumber": "550e8400-e29b-41d4-a716-446655440020",
            "suffix": "23",
            "label": "Support line"
        }
    ]
}
)
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' => '{
    \"pbx_id\": \"550e8400-e29b-41d4-a716-446655440001\",
    \"name\": \"Customer Support\",
    \"description\": \"First-line support team\",
    \"users\": [
        \"550e8400-e29b-41d4-a716-446655440010\",
        \"550e8400-e29b-41d4-a716-446655440011\"
    ],
    \"allow_call_pickups\": true,
    \"allow_default_pbxes_outgoing_phone_numbers\": false,
    \"display_tab_to_everyone_inside_voxbi\": false,
    \"callerIdentities\": [
        {
            \"phoneNumber\": \"550e8400-e29b-41d4-a716-446655440020\",
            \"suffix\": \"23\",
            \"label\": \"Support line\"
        }
    ]
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/groups', false, $context);
$data = json_decode($response, true);
print_r($data);

Sample request

{ … }

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"name": "Customer Support",

"description": "First-line support team",

"users": [ … ],

"550e8400-e29b-41d4-a716-446655440010",

"550e8400-e29b-41d4-a716-446655440011"

"allow_call_pickups": true,

"allow_default_pbxes_outgoing_phone_numbers": false,

"display_tab_to_everyone_inside_voxbi": false,

"callerIdentities": [ … ]

{ … }

"phoneNumber": "550e8400-e29b-41d4-a716-446655440020",

"suffix": "23",

"label": "Support line"

}

]

}

{ … }

"data": { … }

"id": "550e8400-e29b-41d4-a716-446655440000",

"pbx_id": "550e8400-e29b-41d4-a716-446655440001",

"name": "Customer Support",

"description": "First-line support team",

"allow_call_pickups": true,

"allow_default_pbxes_outgoing_phone_numbers": false,

"display_tab_to_everyone_inside_voxbi": false

}

{ … }

"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

{ … }

"message": "Server Error"

}

No matching endpoints

Create a group

Request body · required

Responses