API Docs
Voxbi Cockpit APIs
All endpoints

Update a schedule (user)

Updates a schedule. Every field is optional: send only what changes. The caller must hold the schedules-management permission and manage at least some of the schedule's people; otherwise a 404 is returned.

Scope: send scope_type with the matching selection to change who the schedule is for. The new selection REPLACES the previous one. An update that mentions none of scope_type, companies, departments, employees or department_id leaves the scope exactly as it was, so a plain rename is safe. day_start_time and day_end_time must be sent together.

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>
pbx_id path · string · uuid *
UUID of the PBX tenant.
schedule path · string · uuid *
UUID of the schedule.
accept header · string
example: application/json

Request body · required

Request schema
namestring
Display name of the schedule.
length: 0–150
example: Reception (summer)
scope_typestring
Change who the schedule is for. Send it together with the matching selection; the new selection REPLACES the old one, so switching a department schedule to `employees` drops its departments.
enum: company department employees
example: employees
companiesarray<string>
Companies the schedule covers. Required when `scope_type` is `company`.
items: 1–∞
[]string · uuid
UUID of a company.
departmentsarray<string>
Departments the schedule covers. Used when `scope_type` is `department`.
items: 1–∞
[]string · uuid
UUID of a department.
employeesarray<string>
The exact people the schedule covers. Required when `scope_type` is `employees`.
items: 1–∞
[]string · uuid
UUID of an employee.
department_idstring | null · uuid
Move the schedule's anchor department. The target must be within your validator scope.
example: 550e8400-e29b-41d4-a716-446655440001
days_of_weekarray<integer>
Weekdays the schedule covers.
items: 1–∞
[]integer
ISO weekday number (1 = Monday through 7 = Sunday).
≥ 1≤ 7
day_start_timestring
Start of the daily window as `HH:MM`. Must be sent together with day_end_time.
example: 08:00
day_end_timestring
End of the daily window as `HH:MM`. Must be after day_start_time and sent together with it.
example: 17:00
status_idstring | null · uuid
Default status for generated entries. Must belong to your PBX.
example: 550e8400-e29b-41d4-a716-446655440003
sub_status_idstring | null · uuid
Default sub-status. Must belong to the selected status.
status_filtersarray<string>
Statuses selectable on the grid. Each must belong to your PBX.
[]string · uuid
UUID of an allowed status.
is_activeboolean
Whether the schedule is active.
example:

Responses

The updated schedule.
Response schema
id*string · uuid
Unique schedule identifier.
read-only
example: 550e8400-e29b-41d4-a716-446655440000
name*string
Human-readable name of the schedule template.
example: Sales Team Weekly Plan
departmentobject | null
The schedule's anchor department. Only present when the `department` relation is eager-loaded; otherwise this key is omitted. Null when the scope resolves to no department at all, which happens for a company-scoped schedule whose people hold contracts carrying no department. Such a schedule is valid and fully usable: its people come from the company. Treat this field as optional. Use `departments` for the full list of departments the schedule covers.
idstring · uuid
Unique identifier of the department.
example: 550e8400-e29b-41d4-a716-446655440001
namestring
Display name of the department.
example: Customer Support
scopeType*string
Who the schedule is for: - `company`: everyone contracted with the selected companies. - `department`: everyone contracted in the selected departments (the default, and what a schedule created without a `scope_type` gets). - `employees`: exactly the selected people, who may come from different departments and different companies.
enum: company department employees
example: department
scope*object
The raw selection the schedule was configured with. Only the list matching `scopeType` is populated; the other two are empty arrays. Use this to pre-populate an edit form so it round-trips.
companies*array<object>
Selected companies. Populated only when `scopeType` is `company`.
id*string · uuid
Unique identifier of the company.
example: 550e8400-e29b-41d4-a716-446655440020
name*string
Display name of the company.
example: Northwind Trading
departments*array<object>
Selected departments. Populated only when `scopeType` is `department`.
id*string · uuid
Unique identifier of the department.
example: 550e8400-e29b-41d4-a716-446655440001
name*string
Display name of the department.
example: Customer Support
employees*array<object>
Selected employees. Populated only when `scopeType` is `employees`.
id*string · uuid
Unique identifier of the employee.
example: 550e8400-e29b-41d4-a716-446655440010
fullName*string
Display name of the employee.
example: Jane Smith
departments*array<object>
Every department the schedule covers, resolved from the scope. For a company scope these are the companies' departments; for an employee scope the departments on the selected employees' contracts. An empty array when the scope resolves to no department.
id*string · uuid
Unique identifier of the department.
example: 550e8400-e29b-41d4-a716-446655440001
name*string | null
Display name of the department.
example: Customer Support
employees*array<object>
Everyone the schedule may assign, resolved from the scope. This is the pool the slot assignment pickers and auto-assign draw from; booking anybody outside it is refused with a 422. The same list is available on its own from `GET /{pbx_id}/schedule-management/{schedule}/employees`.
Each item — One assignable person of a schedule: an employee the schedule's scope covers and who may therefore be booked into its slots. Only employees holding a contract that is active today are listed — someone who has left, and someone whose contract has not started yet, is left out whatever the scope type, including a hand-picked `employees` selection. The schedule's `scope` still echoes the raw selection, so an edit form can round-trip what was picked. The department is the one on the employee's most recent contract, supplied so a picker can group or label its options when the schedule spans more than one department. Both department fields are null for an employee whose contract carries no department, which is normal for a company-scoped schedule.
id*string · uuid
Unique identifier of the employee.
example: 550e8400-e29b-41d4-a716-446655440010
fullName*string
Display name of the employee, ordered according to the tenant's first-name or last-name-first preference.
example: Jane Smith
departmentId*string | null · uuid
Identifier of the department on the employee's most recent contract. Null when that contract carries no department.
example: 550e8400-e29b-41d4-a716-446655440002
departmentName*string | null
Display name of the department on the employee's most recent contract. Null when that contract carries no department.
example: Customer Support
daysOfWeek*array<integer>
Weekdays covered by this schedule, stored as ISO 8601 weekday numbers (1 = Monday through 7 = Sunday). Returned as an empty array when no days are configured.
[]integer · int32
ISO 8601 weekday number (1 = Monday, 7 = Sunday).
enum: 1 2 3 4 5 6 7
example: 1
dayStartTime*string | null
Start of the daily working window in `HH:MM` 24-hour format (local wall-clock, no timezone). Null when no start time is configured.
example: 09:00
dayEndTime*string | null
End of the daily working window in `HH:MM` 24-hour format (local wall-clock, no timezone). Null when no end time is configured.
example: 17:30
slotDurationMinutes*integer · int32
Length in minutes of each bookable slot within the daily window. Defaults to the configured Tempus slot duration (typically 30) when not set.
example: 30
statusobject | null
Default status assigned to entries generated from this schedule. Only present when the `status` relation is eager-loaded; null when loaded but no default status is set, and omitted entirely when the relation is not loaded.
idstring · uuid
Unique identifier of the status.
example: 550e8400-e29b-41d4-a716-446655440002
namestring
Display name of the status.
example: Available
subStatusobject | null
Default sub-status assigned to entries generated from this schedule. Only present when the `subStatus` relation is eager-loaded; null when loaded but no default sub-status is set, and omitted entirely when the relation is not loaded.
idstring · uuid
Unique identifier of the sub-status.
example: 550e8400-e29b-41d4-a716-446655440003
namestring
Display name of the sub-status.
example: On Break
statusFilters*array<string>
Identifiers of the statuses that are selectable on this schedule's grid. Used to restrict which statuses planners may apply. Returned as an empty array when no filter is configured (all statuses allowed).
[]string · uuid
Identifier of an allowed status.
example: 550e8400-e29b-41d4-a716-446655440002
isActive*boolean
Whether the schedule is active. Inactive schedules are retained but not used to generate new planning entries.
example: 1
createdAt*string | null · date-time
ISO 8601 timestamp when the schedule was created.
read-only
example: 2024-03-01T08:29:07+00:00
updatedAt*string | null · date-time
ISO 8601 timestamp when the schedule was last updated.
read-only
example: 2024-03-01T08:29:07+00:00
Authorization Token Missing. This error is returned when the authorization token is missing.
Response schema
errorstring
Error message
example: Authorization Token is missing
The caller has no schedules-management scope, or the new selection reaches beyond it. The message is "You do not have permission to manage schedules for this department." for a department (or one resolved from a selected company) outside the scope, and "You do not have permission to manage this employee." for an employee outside it.
Response schema
No response body.
Data Not Found. This error is returned when the requested data is not found.
Response schema
messagearray<string>
[]string
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
put https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/{schedule}
Base URL
Request sample 
curl -X PUT 'https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/{schedule}' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data '{"name":"Reception (summer)"}'
const response = await fetch('https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/{schedule}', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
  body: JSON.stringify({
    "name": "Reception (summer)"
}),
});

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

response = requests.put('https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/{schedule}',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'},
    json={
    "name": "Reception (summer)"
}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'PUT',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
        'content' => '{
    \"name\": \"Reception (summer)\"
}',
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/{schedule}', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
{ … }
"name": "Reception (summer)"
}
No example for this status.
{ … }
"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
No example for this status.
{ … }
"message": [ … ]
"Data not found"
]
}
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