Booking schedules with the Spectrum Vanguard API

Scheduling

The Vanguard API allows developers to programmatically book appointments for club members and guests via its schedules endpoints. Once a schedule has been booked, it may be edited, canceled, and have its participants added or modified.

Finding available schedules to book

Before adding a new a booking, it may be beneficial to check what the different availabilities for a particular schedule are. The get-schedule-availabilities endpoint provides developers with the ability to see which resources and/or instructors are available for a given service at a given site on a particular date. The API will return details about the service as well as the availabilities for any resources or instructors.

The API will return a list of all providers and/or resources regardless of whether they are available on that particular date. For example, an API call to api/scheduler/schedules/123/availabilities?siteId=1086&date=2019-01-01 would return a payload which would include this information:

providers: [
    {
      id: 5,
      name: Samantha Smith,
      availabilityBlocks: [
        { startTime: 07:00, endTime: 10:00 },
        { startTime: 11:00, endTime: 16:00 }
      ]
    },
    {
      id: 10,
      name: Richard Robertson,
      availabilityBlocks: []
    }
  ],
  resources: [
    {
      id: 3,
      name: Tennis Court 1,
      availabilityBlocks: []
    },
    {
      id: 8,
      name: Tennis Court 4,
      availabilityBlocks: [
        { startTime: 09:00, endTime: 10:00 },
        { startTime: 15:30, endTime: 19:00 }
      ]
    }
  ]

This means that Samantha Smith is available between 9 a.m. and 10 a.m. and 3:30 p.m. and 7 p.m. Richard Robertson has no availability set up for that day, even though he is one of the instructors for that service. Tennis Court 1 is also unavailable on that date, but there are two potentially open slots for Tennis Court 4. Please note that the availability blocks returned by this call do not take into account any scheduled bookings and rather return the overall availability configured for each provider or resource on that date. To determine when a provider or resource is actually available to book a particular service the get-schedule-service-provider-availability endpoint and get-schedule-service-resource-availability endpoint can be used. The developer can, at that point, determine which resources and instructors can be booked.

Note: If there are no resources, a resource will not be required to book this schedule, and the same principle applies should an empty array be returned for the instructors property.

Adding a new schedule

The add-schedule endpoint provides the ability to schedule a booking for a member. Please refer to the API documentation for the request body.

The following business rules will apply to creating a new booking for a schedule:

  • The instructor and/or resource must be available for the desired time period.
  • If the service requires split-booking, all participants must be added at the time of booking, and no more participants can be added afterward.
  • Fees will not be collected when a booking is made using the API. However, if a member has charge-to-account enabled on his or her account, that account will be billed during the scheduled billing process.
  • Unless non-members are allowed to book a particular service, only accounts with an active membership — or accounts which have a relationship status that allow them to be treated as members for booking — can be added to a reservation.
  • One of the participants must be designated as the host of the schedule.
  • The booking must adhere to the booking options for the particular service, available via the get-booking-options endpoint, as they define the minimum and maximum number of participants as well as how early or late a schedule can be booked.

Updating a schedule

Should a schedule need to be modified, it must be canceled and then re-booked. Please see the section below on details about how to cancel a schedule.

For managing participants, please refer to the participants-management section of this document.

Canceling a schedule

Should a schedule need to be canceled, it can be accomplished via the cancel-schedule endpoint. This will remove the participants from the service and make the appointment times available for any resources and/or instructors. At this time, however, the API does not refund any charges to the participants' accounts.

Developers should be aware as well that cancellation are subject to rules exposed in the get-booking-options endpoint, as they define how late a schedule can be canceled.

Managing participants in a created schedule

After a scheduled has been created, participants can be added to the schedule — as long as that schedule is not configured for split-booking and the timeframe is valid as described in the are subject to rules exposed in the get-booking-options endpoint. Additionally, the new member can also be designated as the new host if so desired.

Please refer to the add-participant-schedule endpoint for details on the request.

Should a participant need to be removed, that can be accomplished by making a DELETE call to the remove-participant endpoint. Please be aware that participant cancellations are also subject to rules as exposed in the get-booking-options endpoint.