/v1/appointment/book/schedule/calendar

Fetches schedule calendar availability for a specific appointment service at a given business location and region.

Method & URL

Method: GET

Path: /v1/appointment/book/schedule/calendar

Purpose
Use this endpoint to retrieve a calendar view of availability for an appointment-booking flow. The response provides:

A sequence of calendar dates with availability flags.

Per-date metadata (day index, week position, week start/end indicators).

Timezone and week-layout metadata required to correctly render the schedule in a UI.

Authentication

Expects the standard WellnessLiving API authentication used by this collection (for example, a valid bearer or session token configured at the collection/environment level).

Ensure you are authenticated before calling this endpoint; otherwise, the request may fail or return no data.

Required Query Parameters
All of the following query parameters must be provided for meaningful results:

id_region (integer)

Logical region identifier for the booking flow.

Example: 2.

k_business (string or numeric identifier)

Unique business key for which availability is being requested.

Example: 49197.

k_location (string or numeric identifier)

Location key within the business (e.g., a studio, clinic, or branch).

Example: 315968.

k_service (string or numeric identifier)

Service key representing the specific appointment service (e.g., massage, consultation).

Example: 235266.

Key Response Fields (200 OK)
The response body is a JSON object that includes, at minimum, the following keys:

a_date (array of objects)

Represents the calendar dates in the current view.

Each entry describes a single calendar day.

Example entry:

  {
    "dt_date": "2025-12-01 00:00:00",
    "i_week": 1,
    "is_available": false,
    "is_current": false,
    "is_out": true,
    "is_waitlist_only": false,
    "is_week_end": false,
    "is_week_start": false,
    "s_day": 1,
    "s_week": "M"
  }

Field descriptions:

dt_date: Full date (and time at midnight) in YYYY-MM-DD HH:MM:SS format.

i_week: Numeric day-of-week index within the configured calendar week.

is_available: Indicates whether the day has bookable availability for the selected service.

is_current: Indicates whether this entry corresponds to the “current” date in the calendar context.

is_out: When true, the date is outside the valid booking range (e.g., outside allowed window or otherwise not selectable).

is_waitlist_only: When true, the date is not directly bookable but allows waitlist only.

is_week_end: Flags dates that fall at the end of the configured week.

is_week_start: Flags dates that fall at the start of the configured week.

s_day: Numeric day of the month.

s_week: Short day-of-week code (e.g., S, M, T, W, F).

a_timezone_data (object)

Timezone-related metadata for rendering dates/times correctly.

Key fields:

a_timezone (array):

List of supported or relevant timezones for the calendar.

Each item commonly includes fields such as:

k_timezone / k_geo_timezone: Internal timezone keys.

s_timezone: IANA timezone identifier (e.g., America/St_Johns).

text_abbr: Timezone abbreviation (e.g., GMT, NT).

i_shift: Offset from UTC in hours (or fractional hours).

s_title / a_title: Human-readable timezone name.

is_day: Indicates whether daylight-saving rules currently apply.

name: Name of the timezone field key (e.g., "k_timezone").

is_disabled: Whether timezone selection is disabled.

a_week_name (array of objects)

Provides localized or formatted names/abbreviations for days of the week.

Example item:

  {
    "i_day": 1,
    "html_week_day": "Mo"
  }

i_day: Numeric day-of-week index.

html_week_day: Short label suitable for display in a calendar header.

i_week_start / i_week_end (integers)

Indicate which numeric indices represent the start and end of the week (e.g., 7 for Sunday, 6 for Friday/Saturday depending on configuration).

a_time (nullable or array)

May contain time-slot information when applicable. In the sample response it is null, indicating that this view currently focuses on dates rather than individual times.

dt_date (string)

A reference date for the current calendar view (e.g., the first visible date or selected date).

is_waitlist (boolean or null)

Indicates whether the overall view is restricted to waitlist-only state.

k_location (string)

Echoes the requested location key.

status (string)

Overall status of the request. For successful responses this is typically "ok".

s_version (string)

Version token for the underlying data or calendar configuration.

__a_message (array of strings)

Internal or localized message templates associated with the schedule/calendar (e.g., short weekday labels, formatting strings, or user-facing messages). Often contains truncated or encoded resource keys.

Usage Notes

Use the a_date array to render the grid of days in a calendar UI, along with a_week_name, i_week_start, and i_week_end for headers and week layout.

Use is_available, is_out, and is_waitlist_only to determine which dates are selectable, unavailable, or waitlist-only.

Use a_timezone_data and dt_date to present dates in the correct timezone and to interpret availability correctly across regions.

Request

Responses