API Docs
Voxbi Cockpit APIs
All endpoints

Auto-assign the best employee to a slot (user)

Selects the most eligible employee for a slot over the given time window and books them into it, returning the created entry. The chosen employee must be within the caller's schedules-management scope; if no eligible in-scope employee is found a 404 is returned. The slot must belong to a schedule in a department the caller manages.

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

Request body · required

Request schema
start_datetime*string · date-time
Entry start datetime, interpreted in the application timezone.
example: 2026-03-02T09:00:00
end_datetime*string · date-time
Entry end datetime. Must be after start_datetime.
example: 2026-03-02T17:00:00

Responses

The entry was created for the auto-selected employee.
Response schema
dataobject
A single Tempus schedule entry: one assignment of an employee to a time slot within a published schedule, as serialized by `EntryResource`. An entry pins a concrete start and end datetime, an optional comment, and a display colour resolved from the employee's per-schedule colour mapping. This object documents the exact keys returned by the resource, not the raw database columns. The `employee` and `assignedBy` objects are relationship summaries that are only present when their relation is eager-loaded on the model. When the relation is loaded but the related record is missing they are returned as null, and when the relation is not loaded the key is omitted from the payload entirely; integrators should treat both as "no data available". The `color` value is a computed accessor (`color_hex`) looked up from the employee's colour assignment for this schedule, so it can be null when no colour has been configured.
id*string · uuid
Unique identifier of the schedule entry.
read-only
example: 550e8400-e29b-41d4-a716-446655440000
slotId*string · uuid
Identifier of the schedule slot (the recurring template position) this entry was generated from or assigned to.
example: 550e8400-e29b-41d4-a716-446655440001
scheduleId*string · uuid
Identifier of the parent schedule this entry belongs to.
example: 550e8400-e29b-41d4-a716-446655440002
employeeobject | null
Summary of the employee assigned to this entry. Only present when the `employee` relation is loaded; returned as null when the relation is loaded but the employee record cannot be resolved, and omitted entirely when the relation is not loaded.
idstring · uuid
Identifier of the assigned employee.
example: 550e8400-e29b-41d4-a716-446655440003
fullNamestring
Display name of the assigned employee.
example: Jane Smith
color*string | null
Hex colour code used to display this entry, resolved from the employee's colour assignment for this schedule. Null when no colour has been configured for the employee in this schedule. Read-only computed value.
read-only
example: #3B82F6
startDatetime*string | null · date-time
Start of the entry as an ISO 8601 datetime with timezone offset. Null when the start has not been set.
example: 2024-03-01T08:00:00+00:00
endDatetime*string | null · date-time
End of the entry as an ISO 8601 datetime with timezone offset. Null when the end has not been set.
example: 2024-03-01T16:30:00+00:00
comment*string | null
Optional free-form note attached to this entry.
example: Covering the morning reception shift
isException*boolean
Whether this entry is an exception (a manual override) rather than an entry generated from the recurring slot template.
example:
assignedByobject | null
Summary of the user who created this assignment. Only present when the `assignedBy` relation is loaded; returned as null when the relation is loaded but the user cannot be resolved, and omitted entirely when the relation is not loaded.
idstring · uuid
Identifier of the user who made the assignment.
example: 550e8400-e29b-41d4-a716-446655440004
namestring
Display name of the user who made the assignment.
example: Customer Support
assignedAt*string | null · date-time
ISO 8601 timestamp with timezone offset for when the entry was assigned. Null when no assignment time has been recorded.
example: 2024-03-01T07:45:12+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 authenticated user is outside the requested tenant, has no associated employee record, or has an empty schedules-management scope.
Response schema
No response body.
The slot was not found within the caller's scope, or no eligible in-scope employee could be assigned.
Response schema
No response body.
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
post https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/slots/{slot}/auto-assign
Base URL
Request sample 
curl -X POST 'https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/slots/{slot}/auto-assign' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/slots/{slot}/auto-assign', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

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

response = requests.post('https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/slots/{slot}/auto-assign',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
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",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/{pbx_id}/schedule-management/slots/{slot}/auto-assign', false, $context);
$data = json_decode($response, true);
print_r($data);
Sample request
No request example provided.
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.
No example for this status.
{ … }
"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