Locations

The Locations API is used to access, create, and modify any locations on your business' account. The Locations API is connected to the Staff and Services APIs, as staff and services can be optionally filtered depending on which location is chosen for an appointment. Since locations are necessary for creating appointments, as well as setting up both class schedules and service availability, it is crucial for you to familiarize yourself with how to get, create, and update the different locations on your account.

Locations are made accessible to all staff members on a business's account, but staff members will only be able to create appointments at locations to which they are assigned working hours unless they are an admin.

On this page




Locations API Endpoints

These are the endpoints that are available under the /locations path, which lists all the different locations you have added to your business for scheduling purposes.

Endpoint

Description

GET /locations

Returns all location objects on an account in array format. 

GET /locations/{locationId}

Returns a JSON object for specified location.

GET /locationList/reportWithCountReturns an object that contains a list of locations along with a count of the total number of locations that match the parameters passed with the call. 
GET /locationList/reportReturns an object that contains a list of locations that match the parameters passed with the call.
GET /locationList/reportCountReturns a count object that provides the number of locations that match the parameters passed with the call.
GET /locationIdListReturns an object that contains list of the location IDs for the locations that match the parameters passed with the call.
POST /locations

Creates a new location object on an account.

Request body/payload:  Must pass a location object in the request body/payload.

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

Updates an existing location object. All properties can be overwritten except createdDate, businessId, privateUrl, and locationId.

Request body/payload: Must pass a location object with the desired changes made in the request body/payload.

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

DELETE /locations/{locationId}Removes a location object from view by setting its active property to false.




Locations 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
dateRangeTypestringGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as the object that determines the start and end date of the date range. Acceptable values include createdDate and modifiedDate.
endDatestringGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as the end date of appointments to be returned following the API call, formatted as YYYY-MM-DD. 
locationGroupIdintegerGET /locationsShould be set as the unique numeric ID of any location groups that include the locations you want returned following the GET call.
locationGroupIdListinteger arrayGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as a comma-separated list of locationGroupIds connected to the locations to be returned following the API call.
locationIdListinteger arrayGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as a comma-separated list of locationIds of the locations to be returned following the API call.
locationIdListToExcludeinteger arrayGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as a comma-separated list of locationIds of the locations to be excluded from the data that returns following the API call.
locationTypeListstring arrayGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as a comma-separated list of locationTypes of the locations to be returned following the API call.
pageNumberintegerGET /locations, GET /locationList/report, GET /locationList/reportWithCountWorks with the pageSize parameter to determine how data gets returned following a GET call. The pageNumber value represents the number of pages on which the class sessions that get returned appear.
pageSizeintegerGET /locations, GET /locationList/report, GET /locationList/reportWithCountWorks with the pageNumber parameter to determine how data gets returned following a GET call. The pageSize value represents the number of class sessions appearing on each page of class sessions that gets returned.
staffIdintegerGET /locationsShould be set as the unique numeric ID of a staff person that works at locations you want returned following the GET call.
staffIdListinteger arrayGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as a comma-separated list of staffIds connected to the locations to be returned following the API call.
startDatestringGET /locationList/reportWithCount, GET /locationList/report, GET /locationList/reportCount, GET /locationIdListShould be set as the start date of appointments to be returned following the API call, formatted as YYYY-MM-DD. 
workingbooleanGET /locations, GET /locationList/reportCount, GET /locationIdList, GET /locationList/report, GET /locationList/reportWithCountReturns only those locations that have working hours set up.




Locations API Responses

GET /locations
[{
    “active”: true,
    “allowOnline”: true,
    “allowTZChange”: 1,
    “businessId”: 43111,
    “createdDate”: 1501607570000,
    "createdUser": "MORGANKEARNEY"
    “description”: "Bring your pets here to make them sparkle!",
    “directions”: "<p>Log in and add a pet profile</p>",,
    "emailAddress": "groomer@email.com",
    "embedCode": "<iframe src='https://www.timetap.com/pembed/zzmNCJ7B6CQ' frameborder='0' width='840' height='500'> </iframe>",
    "geocode": null,
    “hasWorkScheduleOrClass”: null,
    “inboundBuffer”: null,
    "instructions2": "<p>Only online!</p>",
    “internalDisplayName”: "Sparkle Row",
    “internalName”: null,
    "locationId": 157670,
    "locationName": "Sparkle Row",
    "locationType": "VIRTUAL",
    “logoUrl”: null,
    "modifiedDate": 1643911062373
    “officePhone”: "5551234321",
    “outboundBuffer”: null,
    "privateUrl": "https://www.timetap.com/appts/zzmNCJ7B6CQ",
    “sortWeight”: 0,
    “timeZone”: null,
    "virtualRoomId": "%FAKE%",
    "virtualRoomUrl" "https://fakeurl.com",
    "virtualType": "OTHER",
    "visible": true
}]
GET /locations/{locationId}
{   
    “active”: true,
    “allowOnline”: true,
    “allowTZChange”: null,
    “businessId”: 13245,
    “createdDate”: 1501607570000,
    “description”: "123 Main Street Everywhere, NC 22222",
    “directions”: null,
    “emailAddress”: "janedoe@noemail.com",
    “embedCode: "<iframe src='https://www.timetap.com/pembed/gzvwUZQdH2' frameborder='0' width='840' height='500'> </iframe>",
    “geocode”: "https://www.timetap.com/appts/gzvwUZQdH2“,
    “hasWorkScheduleOrClass”: null,
    “inboundBuffer”: null,
    “internalDisplayName”: "Main Office Location",
    “internalName”: null,
    “locationId”: 12345,
    “locationName”: "My Office 1",
    “locationType”: “PHYSICAL”,
    “logoUrl”: null,
    “officePhone”: "888-888-8888",
    “outboundBuffer”: null,
    “privateUrl”: “http://www.timetap.com/appts/yGmkTKrXtR”,
    "sortWeight": 0,
    "timeZone": {Timezone object for timezone of location-see timezones API page}
}
GET /locationList/reportWithCount
{
    "locations": [
{
        “active”: true,
        “allowOnline”: true,
        “allowTZChange”: 1,
        “businessId”: 43111,
        “createdDate”: 1501607570000,
        "createdUser": "MORGANKEARNEY"
        “description”: "Bring your pets here to make them sparkle!",
        “directions”: "<p>Log in and add a pet profile</p>",,
        "emailAddress": "groomer@email.com",
        "embedCode": "<iframe src='https://www.timetap.com/pembed/zzmNCJ7B6CQ' frameborder='0' width='840' height='500'> </iframe>",
        "geocode": null,
        “hasWorkScheduleOrClass”: null,
        “inboundBuffer”: null,
        "instructions2": "<p>Only online!</p>",
        “internalDisplayName”: "Sparkle Row",
        “internalName”: null,
        "locationId": 157670,
        "locationName": "Sparkle Row",
        "locationType": "VIRTUAL",
        “logoUrl”: null,
        "modifiedDate": 1643911062373
        “officePhone”: "5551234321",
        “outboundBuffer”: null,
        "privateUrl": "https://www.timetap.com/appts/zzmNCJ7B6CQ",
        “sortWeight”: 0,
        “timeZone”: null,
        "virtualRoomId": "%FAKE%",
        "virtualRoomUrl" "https://fakeurl.com",
        "virtualType": "OTHER",
        "visible": true
}],
    "count": 6}
GET /locationList/report
[{
    “active”: true,
    “allowOnline”: true,
    “allowTZChange”: 1,
    “businessId”: 43111,
    “createdDate”: 1501607570000,
    "createdUser": "MORGANKEARNEY"
    “description”: "Bring your pets here to make them sparkle!",
    “directions”: "<p>Log in and add a pet profile</p>",,
    "emailAddress": "groomer@email.com",
    "embedCode": "<iframe src='https://www.timetap.com/pembed/zzmNCJ7B6CQ' frameborder='0' width='840' height='500'> </iframe>",
    "geocode": null,
    “hasWorkScheduleOrClass”: null,
    “inboundBuffer”: null,
    "instructions2": "<p>Only online!</p>",
    “internalDisplayName”: "Sparkle Row",
    “internalName”: null,
    "locationId": 157670,
    "locationName": "Sparkle Row",
    "locationType": "VIRTUAL",
    “logoUrl”: null,
    "modifiedDate": 1643911062373
    “officePhone”: "5551234321",
    “outboundBuffer”: null,
    "privateUrl": "https://www.timetap.com/appts/zzmNCJ7B6CQ",
    “sortWeight”: 0,
    “timeZone”: null,
    "virtualRoomId": "%FAKE%",
    "virtualRoomUrl" "https://fakeurl.com",
    "virtualType": "OTHER",
    "visible": true
}]
GET /locationList/reportCount
{
    "count": 6
}
GET /locationIdList
[
    495584,
    468322,
    81181,
    319495,
    87877,
    282639
]
POST /locations
{
    “active”: true,
    “allowOnline”: true,
    “allowTZChange”: null,
    “businessId”: 13245,
    “createdDate”: 1501607570000,
    “description”: "123 Main Street Anywhere, NC 22222",
    “directions”: null,
    “emailAddress”: "janedoe@noemail.com",
    “embedCode”: "<iframe src='https://www.timetap.com/pembed/gzvwUZQdH2' frameborder='0' width='840' height='500'> </iframe>",
    “geocode”: "https://www.timetap.com/appts/gzvwUZQdH2“,
    “hasWorkScheduleOrClass”: null,
    “inboundBuffer”: null,
    “internalDisplayName”: "Main Office Location",
    “internalName”: null,
    "locationId": 157670,
    “locationName”: "My Office",
    “locationType”: "PHYSICAL",
    “logoUrl”: null,
    “officePhone”: "555-123-4567",
    “outboundBuffer:” null,
    “privateUrl”: “http://www.timetap.com/appts/yGmkTKrXtR”,
    “sortWeight”: 0,
    “tax1Rate”: null,
    “timeZone”: {Timezone object for timezone of location-see timezones API page}
}
PUT /locations/{locationId}
{
    “active”: true,
    “allowOnline”: true,
    “allowTZChange”: 1,
    "businessId": 43111,
    "contactName": "Titus Bigly",
    “createdDate”: 1643910850400,
    "createdUser": "MORGANKEARNEY",
    "description": "We make pets sparkle!",
    "directions": "<p>Log in and add a pet profile</p>",
    "emailAddress": "groomer@noemail.com",
    “embedCode”: "<iframe src='https://www.timetap.com/pembed/gzvwUZQdH2' frameborder='0' width='840' height='500'> </iframe>",
    “geocode”: null,
    “inboundBuffer”: null,
    "instructions2": "<p>Only online!</p>",
    "internalDisplayName": "Sparkles",
    “internalName”: "Sparkles",
    "locationId": 495584,
    "locationName": "Sparkle Row",
    "locationType": "VIRTUAL",
    “logoUrl”: null,
    "modifiedDate": 1643996559720
    "officePhone": "5551234321",
    “outboundBuffer”: null,
    “privateUrl”: “http://www.timetap.com/appts/zzmNCJ7BCQ”,
    "sortWeight": 0,
    “tax1Rate”: null,
    "timeZone": {Timezone object for timezone of location-see timezones API page},
    "virtualRoomId": "%FAKE%",
    "virtualRoomUrl": "https://fakeurl.com",
    "virtualType": "OTHER",
    "visible": true
}




Locations Object Values

Property nameTypeRequiredDescription
activebooleanYesIndicates whether or not the specified location should return on GET calls.
allowOnlineboolean
Indicates whether or not the specified location can be booked by clients.
allowTZchangeinteger
If this value is set to 1, a timezone change is allowed and shows - if it is set to 0, a timezone change is not allowed and shows - if it is set to -1, a timezone change is not allowed and does not show.
businessIdintegerYesProvides a unique numeric ID of the business to which the specified location belongs. 
createdDateinteger
Displays as the date that the specified location was created, in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
createdUserstring
Displays the username of the user who created the specified location.

description

string


Displays as what is set as the Address of the specified location.

directionsstring
Displays as what is set as the Directions of the specified location.
emailAddressstring
Displays as the email address provided for the specified location.
embedCodestring
Provides iframe code that can be used to display scheduler for the specified location based on address given in location description - a back-end component, users cannot alter.
geocodestring
Provides geographical coordinates for the specified location based on address given in location description - a back-end component, users cannot alter.
inboundBufferinteger

Provides built-in estimate of how much time is needed to enter the specified location - displays in minutes.

instructions2string
Displays as what is set as the Additional Directions/Instructions of the specified location.
internalDisplayNamestring

This is a derived, READ ONLY field. It does not get updated directly by API calls.

If the locationName is filled but the internalName is empty, the internalDisplayName would be the same as the locationName - if the internalName is not empty, the internalDisplayName would be the same as the internalName.

internalNamestring
Displays as what is set as the Internal Display Name of the specified location - this is what staff see.
locationIdintegerYes, for PUT callsProvides a unique numeric ID for the specified location. 
locationNamestringYesDisplays as what is set as the Location Name name of the specified location - this is what clients see.
locationTypestringYesImpacts how the description field is shown in the backoffice. Has acceptable values "PHYSICAL", "VIRTUAL", and "VARIABLE". 
logoUrlstring
Displays as URL of specified location.
modifiedDateinteger
Displays as the date that the specified location was last modified, in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
modifiedUserstring
Displays the username of the user who last modified the specified location.

officePhone

string


Displays as what is set as the Office Phone of the specified location.

outboundBufferinteger

Provides a built-in estimate of how much time is needed to leave this location - displayed in minutes.

privateUrlstring
Displays as the URL of the specified location's private scheduling page.
sortWeightinteger
Affects the order in which different locations of a business are displayed to users.
timeZoneobject
Displays the timezones object connected to the this location - for more info, see Timezones API page.
virtualRoomIdinteger
If you take virtual appointments and your meeting room requires a passcode or meeting ID, it would go here.
virtualRoomUrlstring
Displays as the URL for the specified location's virtual meeting room.
virtualTypestring
Displays as the type of service provider used for virtual meetings held at the specified location.