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

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)

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

Parameter	Type	Endpoints to be used with	Description
duration	integer	GET /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.
resourceId	integer	GET /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.
startDate	string	GET /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.
endDate	string	GET /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.

GET /availability/{YYYY}/{MM}/{staffId}/{locationId}/{reasonId}:

[{
    "businessId": 43111,
    "currentMonth": 1675209600000,
    "endDate": {
        "date": 1708041600000,
        "dateId": null,
        "day": 16,
        "dayOfWeek": 5,
        "month": 2,
        "openSlotCount": 0,
        "year": 2024
    },
    "filledDays": [],
    "locationList": null,
    "month": 2,
    "openDays": [{
       "date": 1676592000000,
       "dateId": null,
       "day": 17,
       "dayOfWeek": 5,
       "month": 2,
       "openSlotCount": 0,
       "year": 2023,
       }],
    "staffList": null,
    "startDate": {
        "date": 1676505600000,
        "dateId": null,
        "day": 16,
        "dayOfWeek": 4,
        "month": 2,
        "openSlotCount": 0,
        "year": 2023
    },
    vacationDays: [],
    year: 2023
}]

GET /availability/{YYYY}/{MM}/{DD}/{staffId}/{locationId}/{reasonId}

[{
    "clientEndDate": "2023-02-21",
    "clientEndTime": 1450,
    "clientStartDate": "2023-02-21",
    "clientStartTime": 1400,
    "endTime": 1450,
    "staffEndDate": "2023-02-21",
    "staffEndDateTimeUTC": 1677009000000,
    "staffEndTime": 1500,
    "staffStartDate": "2023-02-21",
    "staffStartDateTimeUTC": 1677006000000,
    "staffStartTime": 1400,
    "startTime": 1400,
    "timeString": "14:00 - 14:50 America/New_York (14:00 - 14:50 ET)",
    "units": [{
        "bundleResourceIdList": [2556],
        "locationId": 282639,
        "professionalId": 298660,
        "reasonId": 159330,
        "resourceId": 16450,
        "roundRobin": false,
        "tandemStaffIdList": null
    }]
}]

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/{YYYY}/{MM}/{staffId}/{locationId}/{reasonId}?duration={reason.visitMinutes}

Property name	Type	Description
businessId	integer	Provides unique numeric ID of the business offering availability.
currentMonth	integer	Provides 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.
filledDays	array	Displays 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.
staffList	string	Displays 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.
vacationDays	array	Displays 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.
year	integer	Displays the year of the specified availability.

Property name	Type	Description
date	integer	Displays the date of the specified day in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
dateId	integer	Provides unique numeric ID for the specified date.
day	integer	Displays as day of the month of the specified date.
dayOfWeek	integer	Displays as day of the week of the specified day (where 0=Sunday, 1=Monday, ..., 6=Saturday).
month	integer	Displays as the month of the specified day.
openSlotCount	integer	Provides the number of open slots of availability for the specified day.
year	integer	Displays as the year of the specified day.

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

Property name	Type	Description
clientEndDate	string	Displays as the date that the specified session ends for clients displayed as YYYY-MM-DD, excludes any buffer.
clientEndTime	integer	Displays as the military time that the specified session ends for clients, excludes any buffer.
clientStartDate	string	Displays as the date that the specified session begins for clients displayed as YYYY-MM-DD, excludes any buffer.
clientStartTime	integer	Displays as the military time that the specified session begins for clients, excludes any buffer.
endTime	integer	Displays as the military time that the specified session ends, excludes any buffer.
staffEndDate	string	Displays as the date that the specified session ends for staff displayed as YYYY-MM-DD, includes any buffer.
staffEndDateTimeUTC	integer	Displays as date & time that the specified session ends for staff in milliseconds elapsed since January 1 1970 UTC format, includes any buffer.
staffEndTime	integer	Displays as the military time that the specified session ends for staff, includes any buffer.
staffStartDate	string	Displays as the date that the specified session begins for staff displayed as YYYY-MM-DD, includes any buffer.
staffStartDateTimeUTC	integer	Displays as date & time that the specified session begins for staff in milliseconds elapsed since January 1 1970 UTC format, includes any buffer.
staffStartTime	integer	Displays as the military time that the specified session begins for staff, includes any buffer.
startTime	integer	Displays as the military time that the specified session begins, excludes 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 name	Type	Description
bundleResourceIdList	array	Provides unique numeric ID of any resources connected to the specified session of availability in array format.
locationId	integer	Provides unique numeric ID of the location connected to the specified session of availability.
professionalId	integer	Provides unique numeric ID of the staff connected to the specified session of availability.
reasonId	integer	Provides unique numeric ID of the service connected to the specified session of availability.
resourceId	integer	Provides unique numeric ID of any resource connected to the specified session of availability.
roundRobin	boolean	Indicates whether or not staff gets assigned to the specified session of availability via round robin.
tandemStaffIdList	array	Provides unique numeric ID of any tandem staff connected to the specified session of availability in array format.

TimeTap API

Availability

Availability API Endpoints

Availability API Parameters

Availability API Responses

Availability Object Values

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

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