Managing availabilities with the Spectrum Vanguard API

This document describes the different availability configurations that Vanguard developers can use to manage resources, employees and services across Spectrum.

Entities that use availabilities

There are three different availabilities that can be managed via the Vanguard API.

Entity	Description	Base path
Employee	Manages the availability of a provider or any other type of employee.	`employees/{employeeId}/availabilities`. A list of all endpoints is available in the API documentation
Resource	Manages the availability of a resource (i.e., a tennis court) at any given site.	`resources/{resourceId}/availabilities`. A list of all endpoints is available in the API documentation
Service	Manages the availability of a service (i.e., racquetball lessons, massage therapy, etc.) at any given site.	`resources/{resourceId}/availabilities`. A list of all endpoints is available in the API documentation

Types of availability in Spectrum

There are four types of availability for any of the entities described above. When managing schedules, developers should be cognizant of the significance of each and their prioritization levels.

Availability type	Description	Example	Priority
Date	This represent a set of availabilities for a particular date in the calendar. This setting is the highest-priority setting, and it will supersede any other type of availability when it comes to scheduling a booking for this entity.	2019-01-05	1
Day of year	This represents a recurring day of the year — i.e., the month and day without the year component, meaning that it is a recurring, yearly schedule.	12-25	2
Template	This represents a date range for which a particular entity may be available. This range is, much like a particular date, is non-recurring.	March 22, 2019 - June 20, 2019	3
Day of week	This represents a recurring, given day of the week	Saturday	4

Understanding prioritization for availabilities

When it comes to finding availabilities for a particular entity, developers should take into consideration the weight of each of the availability types. Below are some examples:

Employee Sally has the Day of week availability configured from 8 a.m. to 5 p.m.
Her day-of-year availability shows that she has zero availability on her birthday, June 20.
By looking at her schedule, she would be available every Monday through Friday, except for June 20, in which it would show zero availabilities.
By updating Sally's date availability to have one schedule from 8 a.m. to 11 a.m. on June 20, 2019, it would show that she would be available on that date in the morning. However, on June 20, 2020, she would again be unavailable.

Availability queries

There are three four different types of queries that can be performed against availabilities.

Overall availability

This provides a set of overall availability results for a particular entity based on a date range. It accepts the following query-string parameters:

startDate: The date range from which to start querying for availabilities.
endDate: The date range from which to end querying for availabilities.
siteId: Applicable to employees only, this query-string parameter scope the results to those availabilities at a particular location.
expanded: Optionally, When set to true, the API will return all the different types of availabilities for each date. Otherwise, the default value of false will only return the highest priority availability for each date based on the rules outlined above.

Example: /resources/23/availabilities?startDate=2019-01-01&endDate=2019-01-06

Date-range availability

This endpoint provides availability for a particular date range for a particular entity. It will return the date availabilities — the highest-weighted values used to determine a particular schedule.

Example: /employees/42/availabilities/date?startDate=2019-01-01&endDate=2019-01-06&siteId=1086

Day-of-week availability

This endpoint provides availability for a week for a particular entity. It will return the day-of-week availabilities — the lowest-weighted values used to determine a particular schedule.

Example: /services/57/availabilities/dayofweek

Note: Whereas the overall-availability endpoint takes into consideration the template and day-of-year availabilities, those individual availabilities are not exposed via the API.

Managing availabilities

In addition to querying by date range, the following operations are available to both date and dayofweek

Querying by ID: Each availabilities will contain an Id property, which can be used to get the availability for that particular date or day of week, as in /employees/42/date/943.
Adding a new entry: Each entry will require an array of availabilities. If an empty array is passed, that equates to having no availabilities for that particular date (e.g., marking an employee as being off on Dec. 25, 2018).

In the case of resources (e.g., a tennis court), the configurationId of the resource must also be provided. A resource configuration is defined in the Spectrum platform as the physical layout of a resource, optionally in relation to other sibling resources. For example, the leftmost lane of a pool can be associated with a "Swimming lessons" configuration as well as a "Swim meet" configuration, and that leftmost lane may have different availabilities depending on how the pool is configured.

Updating an entry by ID: Much like adding a new entry, passing an empty array will result in clearing that schedule for the day.
Removing an entry by ID: This does not clear the availabilities for that particular date or day of week but rather removes that record. That means that, if a date availability is deleted, the availability for that date will be determined by the next-available availability type — day of year, template or day of week.