public-bookings

The Public Bookings API provides read-only access to upcoming venue bookings that are visible on your public calendar. No authentication is required — the API returns only publicly available information.

Base URL

https://app.myhallwizard.com/api

Endpoint

GET /api/v2/{slug}/public-bookings

Replace {slug} with your venue's calendar slug, found in Settings > Venue Details.

Prerequisites

• Your venue's public calendar must be enabled (Settings > Venue Details)

• Your venue must have an active subscription (subscribed, on trial, or free account)

Query Parameters

All parameters are optional.

Example Request

GET /api/v2/my-village-hall/public-bookings?days=14&include_provisional=1

Response

Returns a JSON array of booking objects, ordered by date and start time.

Booking Object

Example Response

[
  {
    "id": 42,
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Yoga Class",
    "confirmed": true,
    "private": false,
    "booking_dt": "2026-03-28",
    "start_tm": "09:00:00",
    "end_dt": "2026-03-28",
    "end_tm": "10:30:00",
    "details": "<p>Weekly yoga session</p>",
    "room_names": "Main Hall",
    "created_at": "2026-01-15T10:30:00.000000Z",
    "updated_at": "2026-03-20T14:22:00.000000Z"
  },
  {
    "id": 87,
    "uuid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "name": "Weekend Festival",
    "confirmed": true,
    "private": false,
    "booking_dt": "2026-04-04",
    "start_tm": "18:00:00",
    "end_dt": "2026-04-05",
    "end_tm": "02:00:00",
    "details": "<p>Annual community festival</p>",
    "room_names": "Main Hall, Meeting Room",
    "created_at": "2026-02-01T09:00:00.000000Z",
    "updated_at": "2026-03-25T11:15:00.000000Z"
  }
]

Multi-Day Bookings

Bookings that span midnight (e.g. 22:00 to 02:00 the next day) have an end_dt that is later than booking_dt. The start_tm and end_tm represent the actual start and end times of the booking.

For example, a booking from Saturday 22:00 to Sunday 02:00 returns:

{
  "booking_dt": "2026-04-04",
  "start_tm": "22:00:00",
  "end_dt": "2026-04-05",
  "end_tm": "02:00:00"
}

Filtering Behaviour

• Time window: Only bookings that overlap with the requested date window are returned. Bookings that have already ended today are excluded.

• Private bookings: Excluded by default. When included via include_private=1, the name field shows "Private booking" (or "Provisional booking") and details is null.

• Provisional bookings: Excluded by default. Set include_provisional=1 to include unconfirmed bookings.

• Incremental sync: Use updated_since to fetch only bookings that have been created or modified since your last request.

HTTP Status Codes

Error Response Format

{
  "slug-value": "Not found"
}

For validation errors (400), the response contains the field names and error messages:

{
  "days": ["The days field must be between 1 and 365."],
  "limit": ["The limit field must be between 1 and 1000."]
}

V0 API (Deprecated)

The original V0 endpoint remains available for backwards compatibility.

GET /api/v0/{slug}/public-bookings

V0 accepts the same parameters and returns the same fields as V2, with two differences:

1. No end_dt field — the response does not include an end date

2. Multi-day bookings are split into separate records per day — each day gets its own record with adjusted times and unique identifiers

How V0 Splits Multi-Day Bookings

A booking from Saturday 22:00 to Monday 02:00 returns three records in V0:

The first record keeps the booking's original id and uuid. Subsequent per-day records receive synthetic identifiers that are:

• Unique — no two records share the same id or uuid

• Deterministic — the same values are returned on every API call

• Traceable — support can derive the synthetic values from the original booking (id via crc32("{id}:{date}"), uuid via md5("{uuid}:{date}") formatted as UUID)

Days that fall outside the query window are omitted.

Migrating from V0 to V2

1. Change /api/v0/ to /api/v2/ in your endpoint URL

2. Handle the new end_dt field — when end_dt differs from booking_dt, the booking spans multiple days

3. Remove any logic that merges split records by id, as V2 returns one record per booking