Getting started

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.