Service Location

The Service Location API is used to access, create and edit the different periods of service availability by location on your business' account. The Service Location API is related to the Services API, as the customWorkSchedule property located on the services API objects displays service location. It is only applicable for reasonTypes of SERVICE (not CLASS, COURSE, or PERSONAL).

On GET /service/{serviceId} calls, the customWorkSchedule property can be set to 0, 1 or 2, which will indicate whether or not the service uses a custom work schedule, as is detailed below -

If the customWorkSchedule is set to 0, the service would be available for booking at all locations whenever the staff that can offer that service have availability at those locations.
If it set to 1, there is a custom schedule for the service and a call should get made to the serviceLocation API.
If it is set to 2, the service is available only at select locations but still whenever the staff that offers that service has availability at those select locations.

When it is set to 2, you would update the serviceLocations property stored on the reason object to have the active property set to true on the locations where it should be available.

Explaining levels on service locations

These levels only apply if the service has its customWorkSchedule property set to 1 or 2.

Level 1 can be thought of as indicating whether the location itself is selected.
The hasLevel2 property indicates whether a selected location has been further refined for availability. If it has not been further refined and the service is available whenever any staff that offer that service are available at that location, the hasLevel2 property will be set to false and all the day objects within the level2 array will be set to a selected property value of false. If it has been further refined and specific days have been indicated, the hasLevel2 property will be set to true and the day objects within the level2 array that have been set will have the selected properties set to true.
The hasLevel3 property is stored on the individual day objects that are contained within the level2 array of each serviceLocation availability object. If that is set to false, that means the service is available for the whole set of hours that the staff is available at that location on that day of the week. If it is set to true, that means that the user has indicated he or she wants the service to only be available for a subset of hours at that location and the level3 property will be filled in with an array of objects that have properties for the start and end times.
The hasLevel4 property is set on the individual objects contained within the level3 property. If set to true, that means the time for the selected day at the selected location included on the serviceLocation’s availability object has at least a startDate and potential and endDate property filled in as well. If set to false, the times are to continue indefinitely and no start date or end date will be set for the time.

On this page

These are the endpoints that are available under the /serviceLocation path, which lists all the service availability your business offers by location.

Endpoint

Description

GET /serviceLocation/service/{reasonId}

Returns all serviceLocation objects for the specified reason in array form - these objects describe the locations, days and hours that this service has availability.

POST /serviceLocation/service/{reasonId}

Creates a new set of serviceLocation availability objects for the specified service or updates an existing set of serviceLocation availability objects for a service.

Request body/payload: Must pass an array of serviceLocation availability objects in the request body/payload.

For these calls, you need to pass a serviceLocation object with all required fields and any fields you want to set or update filled in the body of the payload. We have an example of a serviceLocation object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

There are no parameters included with serviceLocation calls.

POST /serviceLocation/service/{reasonId}

[{
    "description": "Green office",
    "hasLevel2": true,
    "level2": [{
        "day": "Monday",
        "dayOfWeek": 1,
        "hasLevel3": true,
        "level3": [{
            "endDate": 1703203200000,
            "endDateToggle": false,
            "endTime": 1200,
            "hasLevel4": true,
            "startDate": 1702857600000
            "startDateToggle": false,
            "startTime": 1000,
            "toggled": false
        }],
        "selected": true
    }],
    "locationId": 282639,
    "selected": true
}]

GET /serviceLocation/service/{reasonId}

[{
    "description": "Beach Office",
    "hasLevel2": true,
    "level2": [{
        "day": "Monday",
        "dayOfWeek": 1,
        "hasLevel3": true,
        "level3": [{
            "endDate": 1548892800,
            "endTime": 1700,
            "hasLevel4": true,
            "startDate": 1548806400,
            "startTime": 1300
        }],
        "selected": true
    }],
    "locationId": 81181,
    "selected": true
}]

POST/serviceLocation/service/{reasonId}

[{
    "description": "Green office",
    "hasLevel2": true,
    "level2": [{
        "day": "Monday",
        "dayOfWeek": 1,
        "hasLevel3": true,
        "level3": [{
            "endDate": 1703203200000,
            "endTime": 1200,
            "hasLevel4": true,
            "startDate": 1702857600000,
            "startTime": 1000
        }],
        "selected": true
    }],
    "locationId": 282639,
    "selected": true
}]

Level 1/Location array table:

Property name	Type	Required	Description
description	string	Yes	Displays as the location name of the specified service location.
haslevel2	boolean		Indicates whether or not the specified service location has level 2 service availability set up.
level2	array		Provides an array of 7 objects that represent the days of the week that can be selected to further refine service availability by location. Definitions of properties within an object on this array are defined in the table labeled "Level 2/Days array table" below.
locationId	integer	Yes	Displays as the location ID of the specified service location.
selected	boolean		Indicates whether or not the specified location has service availability.

Level 2/Days array table:

Property Name	Type	Description
day	string	Displays as a string representation of the specified day of the week.
dayOfWeek	integer	Displays as an integer representation of the specified day of the week, where 0 = Sunday, 1 = Monday, ..., 6 = Saturday.
hasLevel3	boolean	Indicates whether or not the specified service location has level 3 service availability set up.
level3	array	Provides an array of objects that represent different times of the day that can be selected to further refine service availability by location. Definitions of properties within an object on this array are defined in the table labeled "Level 3/Times array table" below.
selected	boolean	Indicates whether or not this locations offers service availability on the specified day of the week.

Level 3/Times array table:

Property Name	Type	Description
endDate	integer	Displays as what is set as the end date of the specified set times of service availability in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
endTime	integer	Displays as what is set as the end time of the specified set times of service availability using military time.
hasLevel4	boolean	Indicates whether the specified time for the specified day for the specified location has a date range that applies to it. If this is set to true, then it would be expected that at least the startDate property on this level has been filled in with a value.
startDate	integer	Displays as what is set as the start date of the specified set times of service availability in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
startTime	integer	Displays as what is set as the start time of the specified set times of service availability using military time.

TimeTap API

Service Location

Explaining levels on service locations