External API: get bookings
The External API lets you export booking data from UnSpot into your own systems — BI dashboards, facility management, payroll or security tools. This page documents the bookings endpoint.
Authentication
Create an API connection of type Bookings in Administration > Integrations > External API and copy the token (available to the Owner and Integrations admin roles). Pass it in every request:
Authorization: Bearer <token>Requests without a valid token return 401. If you exceed the rate limit, the API returns 429 with a Retry-After header.
Get bookings — GET /api/external/v1/bookings
Returns bookings of one type (desks, parking or meeting rooms) whose start time falls within the requested period. Results are sorted by start time, newest first.
| Query parameter | Type | Required | Description |
|---|---|---|---|
bookingType | string | yes | DESK, PARKING or MEETING_ROOM |
startDate | integer | yes | Unix timestamp (seconds). Bookings starting after this moment. |
endDate | integer | yes | Unix timestamp (seconds). Bookings starting before this moment. The range may not exceed 92 days. |
Example request
curl -H "Authorization: Bearer $TOKEN" \
"https://acme.unspot.com/api/external/v1/bookings?bookingType=DESK&startDate=1751328000&endDate=1751932800"Example response — 200
{
"message": "OK",
"body": {
"items": [
{
"bookingStart": "2026-07-01 09:00:00",
"bookingEnd": "2026-07-01 18:00:00",
"duration": "09:00:00",
"bookingOffice": "HQ Berlin",
"ownerName": "Jane Doe",
"ownerEmail": "jane.doe@example.com",
"ownerDepartment": "Engineering",
"bookingPlace": "Desk 4.12",
"guestName": null
}
]
}
}| Response field | Description |
|---|---|
bookingStart / bookingEnd | Booking period, Y-m-d H:i:s |
duration | Length of the booking, HH:MM:SS |
bookingOffice | Office name |
ownerName / ownerEmail | Person the booking belongs to. For guest bookings — the guest’s name and email. |
ownerDepartment | Department of the owner (null for guests) |
bookingPlace | Desk, parking place or room name |
guestName | Guest name for desk/parking guest bookings, otherwise null |
Errors and limits
All External API responses are wrapped in an envelope {"message": ..., "body": ...}. Errors are returned as:
{ "message": "Date range cannot exceed 92 days", "errors": [] }- 400 —
bookingType must be one of: DESK, PARKING, MEETING_ROOM;startDate cannot be greater than endDate;Date range cannot exceed 92 days. - 401 — missing or invalid token.
- 429 — more than one request per 10 seconds per workspace; wait for
Retry-After.
Tip: to export a long history, iterate over consecutive 92-day windows with one request every 10 seconds.
