Skip to content
Developers
Voxbi Cockpit APIs
API Guides
All endpoints

Tempus calendar

Every employee's calendar events across the PBX (data.events), and the public and custom holidays of the companies in scope (data.holidays). filter[type] picks what is returned: legal (holiday), illness, special, home_office, public_holiday, custom_holiday; omit it for all. Narrow events to departments and companies by the employee's active contract, or leave both out for everyone. Holidays follow the same company and department scope (a department scopes to its companies), and filter[country] narrows public holidays to those countries. filter[from] and filter[to] are required; the window spans at most 366 days, both ends included. Statuses pending, approved and pending_removal. Any employee of the PBX may read it. The events are in data, sorted by start, not paginated. Colors per type come from GET /tempus/api/v2/{pbx}/calendar/colors.

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 path · string · uuid *
UUID of the PBX tenant. Must be the tenant the token belongs to; anything else is refused with 403 rather than answered from another tenant.
filter[type] query · string
Comma-separated: `legal`, `illness`, `special`, `home_office`, `public_holiday`, `custom_holiday`. Omit for all.
filter[department_id] query · string
Narrow to one or more department UUIDs (comma-separated), by the employee's active contract. Omit for every department.
filter[company_id] query · string
Narrow to one or more company UUIDs (comma-separated), by the employee's active contract. Omit for every company.
filter[country] query · string
Narrow public holidays to these ISO 3166-1 alpha-2 country codes (comma-separated, case-insensitive). An unknown code matches nothing. Does not affect events or custom holidays.
filter[from] query · string · date *
First day of the window (`Y-m-d`). Events overlapping the window are returned.
filter[to] query · string · date *
Last day of the window (`Y-m-d`), on or after `filter[from]`. The window spans at most 366 days, both ends included.
accept header · string
example: application/json

Responses

OK. Events and holidays, not paginated.
Response schema
dataobject
eventsarray<object>
Sorted by start.
idstring · uuid
example: 550e8400-e29b-41d4-a716-446655440030
employee_idstring · uuid
example: 550e8400-e29b-41d4-a716-446655440001
employee_namestring | null
example: Jane Smith
department_idstring | null · uuid
Department of the employee's active contract; null when none.
example: 550e8400-e29b-41d4-a716-446655440042
company_idstring | null · uuid
Company of the employee's active contract; null when none.
example: 550e8400-e29b-41d4-a716-446655440050
typestring
Rows of the retired `absence` type are reported as `legal`.
enum: legal illness special home_office
example: legal
sub_typestring | null
Sub-type where applicable (e.g. sick_employee, training).
statusstring
enum: pending approved pending_removal
example: approved
startstring · date
example: 2026-07-07
endstring · date
example: 2026-07-09
working_daysnumber
Working days the event consumes, half days as 0.5, measured against the employee's own scheduled day. Decode as a float.
example: 3
total_secondsinteger
Sum of `days[].seconds`.
example: 86400
workshift_seconds_per_dayinteger
One full working day for this employee, in seconds (28800 on an 8h shift). 0 when no contract or work shift resolves.
example: 28800
daysarray<object>
Each working day the event covers, ascending. Weekends and public holidays are not listed.
datestring · date
example: 2026-07-07
secondsinteger
Seconds booked that day, scaled to the employee's own day.
example: 28800
is_half_dayboolean
True when the day's seconds fall short of `workshift_seconds_per_day` by more than 900.
example:
start_timestring | null
HH:MM; set only on a half-day first day.
end_timestring | null
HH:MM; set only on a half-day last day.
holidaysarray<object>
Sorted by date.
Each item — A public or custom holiday. Holidays belong to companies, not employees: `company_ids` lists the companies in scope it applies to.
typestring
enum: public_holiday custom_holiday
example: public_holiday
datestring · date
example: 2026-07-14
namestring
example: National Day
is_half_dayboolean
Public holidays only; custom holidays are always whole days.
example:
half_day_partstring | null
Which half is off on a half-day public holiday; null otherwise.
enum: morning afternoon null
country_codestring | null
ISO 3166-1 alpha-2 code of the country the public holiday comes from, the value `filter[country]` takes; null for custom holidays.
example: LU
company_idsarray<string>
Companies in scope the holiday applies to.
[]string · uuid
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 belongs to another tenant or has no employee record.
Response schema
No response body.
Missing or invalid `filter[from]` / `filter[to]`, `to` before `from`, a window longer than 366 days, an unknown `filter[type]`, a department or company id that is not a UUID, or a country that is not a two-letter code.
Response schema
messagestring
errorsobject
Free-form object
get https://cockpit.voxbi.com/api/v1/v2/{pbx}/calendar
Base URL
Request sample 
curl -X GET 'https://cockpit.voxbi.com/api/v1/v2/{pbx}/calendar' \
  -H 'Authorization: Bearer YOUR_TOKEN'
const response = await fetch('https://cockpit.voxbi.com/api/v1/v2/{pbx}/calendar', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${YOUR_TOKEN}`,
  },
});

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

response = requests.get('https://cockpit.voxbi.com/api/v1/v2/{pbx}/calendar',
    headers={'Authorization': f'Bearer {YOUR_TOKEN}'}
)
response.raise_for_status()
data = response.json()
print(data)
<?php
$context = stream_context_create([
    'http' => [
        'method'  => 'GET',
        'header'  => "Content-Type: application/json\r\nAuthorization: Bearer YOUR_TOKEN",
    ],
]);

$response = file_get_contents('https://cockpit.voxbi.com/api/v1/v2/{pbx}/calendar', false, $context);
$data = json_decode($response, true);
print_r($data);
{ … }
"data": { … }
"events": [ … ],
{ … },
"id": "550e8400-e29b-41d4-a716-446655440031",
"employee_id": "550e8400-e29b-41d4-a716-446655440002",
"employee_name": "Alex Doe",
"department_id": "550e8400-e29b-41d4-a716-446655440042",
"company_id": "550e8400-e29b-41d4-a716-446655440050",
"type": "illness",
"sub_type": "sick_employee",
"status": "approved",
"start": "2026-07-10",
"end": "2026-07-13",
"working_days": 2,
"total_seconds": 57600,
"workshift_seconds_per_day": 28800,
"days": [ … ]
{ … },
"date": "2026-07-10",
"seconds": 28800,
"is_half_day": false,
"start_time": null,
"end_time": null
},
{ … }
"date": "2026-07-13",
"seconds": 28800,
"is_half_day": false,
"start_time": null,
"end_time": null
}
]
},
{ … }
"id": "550e8400-e29b-41d4-a716-446655440032",
"employee_id": "550e8400-e29b-41d4-a716-446655440005",
"employee_name": "Sam Lee",
"department_id": null,
"company_id": "550e8400-e29b-41d4-a716-446655440050",
"type": "legal",
"sub_type": null,
"status": "pending",
"start": "2026-07-15",
"end": "2026-07-15",
"working_days": 0.5,
"total_seconds": 14400,
"workshift_seconds_per_day": 28800,
"days": [ … ]
{ … }
"date": "2026-07-15",
"seconds": 14400,
"is_half_day": true,
"start_time": "12:00",
"end_time": null
}
]
}
],
"holidays": [ … ]
{ … },
"type": "public_holiday",
"date": "2026-07-14",
"name": "National Day",
"is_half_day": false,
"half_day_part": null,
"country_code": "LU",
"company_ids": [ … ]
"550e8400-e29b-41d4-a716-446655440050"
]
},
{ … }
"type": "custom_holiday",
"date": "2026-07-24",
"name": "Summer party",
"is_half_day": false,
"half_day_part": null,
"country_code": null,
"company_ids": [ … ]
"550e8400-e29b-41d4-a716-446655440050"
]
}
]
}
}
{ … }
"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": "The calendar range cannot exceed 366 days.",
"errors": { … }
"filter.to": [ … ]
"The calendar range cannot exceed 366 days."
]
}
}