Conventions
These apply across the whole API.
Base URL and format
https://api.clearooms.com/api/v1- Send request bodies as JSON, with
Content-Type: application/json. - Always send
Accept: application/json. Without it, some errors come back as HTML instead of JSON. - Use HTTPS. Requests are authenticated with a Bearer token.
IDs
Every record is identified by a UUID, such as 573657f8-ad17-49eb-95ce-d0f2b8515900.
Dates and time zones
Timestamps are sent and returned as local date-time strings, without an offset:
| Where | Format | Example |
|---|---|---|
| Desk bookings | YYYY-MM-DD HH:MM:SS |
2025-05-08 08:00:00 |
| Meetings | YYYY-MM-DD HH:MM. Sent in the time zone you give in start_time_tz/end_time_tz, and returned in UTC |
2025-05-11 09:30 and Europe/London |
| Visitors | YYYY-MM-DD HH:MM |
2025-05-14 14:00 |
Time zones are IANA names, such as Europe/London. GET /timezones lists the ones Clearooms accepts. Desk bookings use the time zone of the desk's office.
Lists and pagination
Most list endpoints return every matching record as a plain JSON array, and single records are returned as a plain object, with no data wrapper. Some list endpoints return pages instead. Each one's reference entry says how: some always paginate, others paginate only when you send page or paginate, and some accept per_page. For example, GET /users paginates when you send page, 15 per page by default.
A paginated response has data, plus links and meta:
{
"data": [],
"links": {
"first": "https://api.clearooms.com/api/v1/users?page=1",
"last": "https://api.clearooms.com/api/v1/users?page=4",
"prev": null,
"next": "https://api.clearooms.com/api/v1/users?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 4,
"path": "https://api.clearooms.com/api/v1/users",
"per_page": 15,
"to": 15,
"total": 52
}
}Follow links.next until it is null.
Errors
Errors use standard HTTP status codes and a JSON body with a message.
| Status | Meaning |
|---|---|
400 |
The request couldn't be processed. |
401 |
The token is missing, invalid or revoked. |
403 |
The token doesn't have the scope this needs, or its user can't act on this record. |
404 |
The record doesn't exist, or the token can't see it. |
422 |
Validation failed. See below. |
429 |
Too many requests. Wait, then retry with backoff. |
5xx |
Something went wrong on our side. Retry later, and contact us if it continues. |
A 422 lists the problem with each field:
{
"message": "The desk id field is required.",
"errors": {
"desk_id": ["The desk id field is required."]
}
}Error messages are written for people and can change, so check the status code and the keys in errors rather than the message text.
Languages
Clearooms is available in English (UK), which is the default, English (US), Dutch, French, German, Italian, Spanish and Welsh. Some text the API returns, such as the subject of a private meeting and error messages, is translated into the user's language.