Availability

The Availability API is used to display a list of dates and times that are available for a service or class to be booked. The Availability API is separate from the Working Hours API, although the two are connected, as when a staff person POSTs their workingHours for a particular day he or she is setting up the hours available for work WITHOUT accounting for any other appointments or periods of time off. Availability reads from the workingHours data table to see what hours a person has vacant then subtracts their other time commitments to get the hours they have available, and then organizes those hours into timeslots depending on how long a service or class takes. Since availability lets your clients know when they can sign up for your business' appointments, it is crucial for you to familiarize yourself with how to access availability on your account.


Please note that this API should not be used for displaying a calendar, but only for booking an appointment. 

On this page




Availability API Endpoints

These are the endpoints that are available under the /availability path, which show what hours your business has available to take new appointments.

Endpoint

Description

GET /availability/{YYYY}/{MM}/{staffId}/{locationId}/{reasonId}?duration={reason.visitMinutes}

Returns an object with properties that can be used to determine what days in the specified month a staff person has availability to fit an appointment with specified staffId, locationId, and reasonId, and with the duration passed as a parameter. This API call only provides the dates that offer open timeslots, and does not accurate calculation for each slot. Use the GET /availability/{YYYY}/{MM}/{DD}/{staffId}/{locationId}/{reasonId} call to provide information about the details for that day.

Can be used with reasonTypes of both SERVICE and CLASS.

GET /availability/{YYYY}/{MM}/{DD}/{staffId}/{locationId}/{reasonId}?duration={reason.visitMinutes}

Returns an array of timeslot objects that display the times during the chosen day that the specified staff person has available to take an appointment for specified service at specified location. Can be used with reasonType of SERVICE. A separate endpoint should be used when determining timeslots for classes, since classes allow multiple customers to book for the same time slot. Please read our classschedule API documentation here.

GET /availability/location/{locationId}/service/{reasonId}Returns the dates of availability for all staff for the specified location and service in array format. Requires parameters startDate and endDate (described in table below)




Availability API Parameters

Data points passed on in the request URL portion of the API call that are used to filter the data being requested. 

ParameterTypeEndpoints to be used withDescription
durationintegerGET /availability/{YYYY}/{MM}/{staffId}/{locationId}/{reasonId}, GET /availability/{YYYY}/{MM}/{DD}/{staffId}/{locationId}/{reasonId}

Is set to the duration of the reason that you are looking to get the availability for. Typically this is the reason’s visitMinutes property but if the reason is a multi-duration service that has a durationList it could be any of the durations in the durationList. The data that is sent back from the availability GET calls when the duration parameter is filled in is filtered to make sure the appointment slots could accommodate this duration.

resourceIdintegerGET /availability/{YYYY}/{MM}/{staffId}/{locationId}/{reasonId}, GET /availability/{YYYY}/{MM}/{DD}/{staffId}/{locationId}/{reasonId}Is set to the resourceId you want to use for this appointment. The response in the GET call will be used to make sure that the days and timeslots sent back are when the resource is free and available for the appointment.
startDatestringGET /availability/location/{locationId}/service/{reasonId}This parameter is required on this endpoint. Should be set to the start date of the range of dates that you want availability to return for. Must be passed as YYYY-MM-DD.
endDatestringGET /availability/location/{locationId}/service/{reasonId}This parameter is required on this endpoint. Should be set to the end date of the range of dates that you want availability to return for. Must be passed as YYYY-MM-DD.




Availability API Responses

GET /availability/{YYYY}/{MM}/{staffId}/{locationId}/{reasonId}:
[{
	"businessId": 43111,
    "currentMonth": 1541030400000,
    "endDate": {
		"date": 1564704000000,
		"dateId": null,
		"day": 2,
		"dayOfWeek": 5,
		"month": 8,
		"openSlotCount":0
		"year": 2019
	},
	"filledDays": [],
    "locationList": null,
    "month": 11,
	"openDays": [{
        "date": 1543190400000,
        "dateId": null,
        "day": 26,
        "dayOfWeek": 1,
        "month": 11,
        "openSlotCount": 0,
        "year": 2018
    }],
    "staffList": null,
    "startDate": {
        "date": 1533168000000,
        "dateId": null,
        "day": 2,
        "dayOfWeek": 4,
        "month": 8,
        "openSlotCount": 0,
        "year": 2018,
    },
	"vacationDays": [],
	"year":1 2018
}]
GET /availability/{YYYY}/{MM}/{DD}/{staffId}/{locationId}/{reasonId}:
[{
	"available": true,
	"deleted": false,
	"endDate": null,
	"endTime": 1700,
	"slotCount": 36,
	"slotMax": 36,
    "staffEndTime": 1700,
    "staffStartTime": 1400,
    "startTime": 1400,
	"timeString": "02:00 PM - 05:00 PM",
	"units": [{
		"locationId": 81181,
		"professionalId": 82275,
		"reasonId": 158196,
		"resourceId": 2556
	}]
}]
GET /availability/location/{locationId}/service/{reasonId}
[{
    "clustered": false,   
    "date": "2018-12-11",
    "timeSlots": [{
        "available": true
        "clientTime": 1200,
        "deleted": false,
        "endDate": null,
        "endTime": 1300,
        "slotCount": 12,
        "slotMax": 12,
        "staffEndTime": 1300,
        "staffStartTime": 1200,
        "startTime": 1200,
        "timeString": "12:00 PM - 1:00 PM",
        "units": [{ 
            "professionalId": 41681,
            "locationId": 28745,
            "reasonId": 93790,
            "resourceId": null
         }],
    }],
}]


  • For the class schedule availability endpoint, please refer to the Class Schedule API page.




Availability Object Values

availability/{YYYY}/{MM}/{staffId}/{locationId}/{reasonId}?duration={reason.visitMinutes}

Property nameTypeDescription

businessId

integer

Provides unique numeric ID of the business offering availability. 

currentMonthintegerProvides current month as calculated by milliseconds elapsed since January 1, 1970 00:00:00 UTC form.

endDate

object

Displays an object containing details about the end date of this period of availability. Definitions of the properties within this object are defined in the table below. 

filledDaysarrayDisplays an array of of dates that no longer have open slots available. Definitions of properties within an object on this array are defined in the table below. 

locationList

string

Displays a list of the locations that have availability.

month

integer

Displays a one or two digit number that indicates the month of availability. 

openDays

array

Displays an array of the dates which still have open slots available and filledPercent below 100. Definitions of the properties within an object on this array are defined in the table below. 

staffListstringDisplays a list of staff members that have availability. 

startDate

object

Displays an object containing details about the start date of this period of availability. Definitions of the properties within this object are defined in the table below. 

vacationDaysarrayDisplays an array of dates set aside for staff time off. Definitions of the properties within an object on this array are defined in the table below. 
yearintegerDisplays the year of the specified availability.
Property nameTypeDescription
dateintegerDisplays the date of the specified day in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
dateIdintegerProvides unique numeric ID for the specified date.
dayintegerDisplays as day of the month of the specified date.
dayOfWeekintegerDisplays as day of the week of the specified day (where 0=Sunday, 1=Monday, ..., 6=Saturday).
monthintegerDisplays as the month of the specified day.
openSlotCountintegerProvides the number of open slots of availability for the specified day.
yearintegerDisplays as the year of the specified day. 

availability/{YYYY}/{MM}/{DD}/{staffId}/{locationId}/{reasonId}?duration={reason.visitMinutes}

Property nameTypeDescription

available

boolean

Indicates whether or not the specified session of availability is still available. 

deleted

boolean

Indicates whether or not the specified session has been deleted.

endDate

integer

Displays the date that the specified session is set to end.

endTime

integer

Displays as the military time that the specified session ends, not including any buffer. 

staffEndTimeintegerDisplays as the military time that the specified session ends for staff, includes any buffer. 
staffStartTimeintegerDisplays as the military time that the specified session begins for staff, includes any buffer.

timeString

string

Provides a string display of the start and end times of the specified session, using AM/PM format. 

units

array

Ties the staff, location, reason, and resource to the availability slot. Definitions of the properties within an object on this array are defined in the table below.

Property nameTypeDescription
locationIdintegerProvides unique numeric ID of the location connected to the specified session of availability.
professionalIdintegerProvides unique numeric ID of the staff connected to the specified session of availability. 
reasonIdintegerProvides unique numeric ID of the service connected to the specified session of availability.
resourceIdintegerProvides unique numeric ID of any resource connected to the specified session of availability.