Page Comparison

Anchor

	topOfPage
	topOfPage

The Services API is used to access, create, and modify the reasons on your business' account, as services are commonly referred to as reasons on the TimeTap site. The Services API is connected to the Locations and Staff APIs, in that reasons can be optionally filtered depending on which staff and/or location was chosen for an appointment. Since reasons are necessary for creating appointments, as well as setting up class schedules, it is crucial for you to familiarize yourself with how to get, create, and update the different reasons on your account.

Reasons are made accessible to all users on a business's account, but staff members will only be able to create appointments for services to which they are assigned, unless that staff person is an admin.

Info

title	On this page

Table of Contents

These are the endpoints that are available under the /services path, which lists all the different services your business offers using TimeTap.

Endpoint	Description
GET /services	Returns all reason objects on an account in array format. If the user has admin privileges, he will see all services at all locations under his or her business, location Super Users see all services at their location, while users with User privileges will only see their own services.
GET /services/{reasonId}	Returns a JSON object for specified reason.
GET /services/{reasonId}/serviceStaff	Returns an array of data objects for active staff members who are allowed to offer the specified service. If the active property is set to true, the staff is allowed to offer the service, and if it is set to false, they not allowed to offer the service.
GET /services/{reasonId}/quota	Returns a number of how many appointments have been set as the quota for that specific reasonId on the date provided by the parameter.
GET /reasonList/reportWithCount	Returns an object that contains a list of reasons along with a count of the total number of reasons that match the parameters passed with the call.
GET /reasonList/report	Returns an object that contains a list of reasons that match the parameters passed with the call.
GET /reasonList/reportCount	Returns a count object that provides the number of reasons that match the parameters passed with the call.
GET /reasonIdList	Returns a list of reasonIds available on the account. If no parameters are passed, it will just return all active reasonIds on the account.
POST /services	Creates a new reason by passing a reason object with all required properties properly configured. Request body/payload: Must pass a reason object in the request body/payload. For these calls, you need to pass a services 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 services object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.
POST /services/{reasonId}/serviceStaff	Updates the array for specified reasonId to allow more staff members to offer that reason or service by simply changing the active property accordingly. Request body/payload: Must pass a reason object in the request body/payload.
PUT /services/{reasonId}	Updates specified reason with any new values you may have changed on the properties. Request body/payload: Must pass a reason object with the desired changes made in the request body/payload. For these calls, you need to pass a services 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 services object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.
DELETE /services/{reasonId}	Deletes a reason or service by setting its active property to false. Open appointments for the service will not be deleted, but clients will no longer be able to schedule new appointments for the service.

Data points passed on in the request URL portion of the API call that are used to filter the data being requested. All services parameters are associated with the GET /services endpoint only.

Parameter	Type	Endpoints to be used with	Description
addOnReasonIdList	string array	GET /reasonIdList	Should be set as a comma-separated list of reasonIds that are of reasonType ADDON. When set, the return values will be reasonIds that have the passed reasonIds set in the reason object's `addOnReasonIds` property The reason object can now support a new value in the reasonType property field called ADDON, and has a new property called `addOnReasonIdList`. If the reason is of reasonType SERVICE, CLASS, or COURSE, then this property can that can be set to a number array for all the reasons of reasonType ADDON that can be offered with the primary reason (SERVICE CLASS or COURSE) .
calendarIdList	integer array	GET /reasonIdList	Should be set as a comma-separated list of the calendarIds which will then return a unique set of reasonIds assigned to passed calendarId parameter.
classesOnly	boolean	GET /services	If set to true, only reasons of reasonType = CLASS will return. If passed as false, only reasons with a different reasonType will return.
date	string	GET /services/{reasonId}/quota	Should be set as the date that you want to see a services' quota for.
dateRangeType	string	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Used in conjunction with endDate and startDate parameters. Acceptable values are: createdDate (default) and modifiedDate. If all three parameters are passed, then the API will only return reasonIds that fall within the defined date range based on the dateRangeType selected here.
endDate	string	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Used in conjunction with dateRangeType and startDate parameters. Date should be set in format of YYYY-MM-DD. If all three parameters are passed, then the API will only return reasonIds that fall within the defined date range based on the dateRangeType that is being looked for.
excludeAddOns	boolean	GET /reasonIdList	If not passed or passed as true, only reasons whose reasonType property is not set to ADDON will return. If passed as false, then reasonIds for reasons of reasonTypes including ADDON will return.
excludeClasses	boolean	GET /services	If set to true, only reasons where reasonType is not CLASS will return. If passed as false, then all reasonTypes will return, including reasons where reasonType = CLASS.
excludePersonal	boolean	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	If set to true, will prevent reasons of reasonType = PERSONAL from returning.
includePersonal	integer	GET /services	Can be set to either 0 or 1. If set to 0, the call will return with only SERVICE, CLASS, and COURSE reasonTypes. If set to 1, the call will return with SERVICE, CLASS, COURSE, and PERSONAL reasonType.
locationGroupIdList	integer array	GET /reasonIdList	If you pass the groupId of an active location group on your account, only reasons that are bookable at the locations within that group will return.
locationId	string	GET /services	Returns an array of all reasons offered at a location. If reasonType = SERVICE, service availability is dependent on whether staff members that can offer the service have working hours at the location and if the service’s location specific availability has the location selected. If reasonType = CLASS, availability is dependent on whether the location has dates and times set up for it on its class schedule. If reasonType = COURSE, availability is dependent on whether the location has the course sets set up.
locationIdList	integer array	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Should be set as a comma-separated list of locationIds and will only return reasonIds that are bookable at the passed locationIds.
onlyAddOns	boolean	GET /reasonIdList	If set to true, only reasons whose reasonType property is set to ADDON will return. If not passed or passed as false, then no check is made to exclude reasonTypes other than ADDON.
onlyPersonal	boolean	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	If set to true, will only return reasons of reasonType = PERSONAL.
order_field	string	GET /reasonList/reportWithCount, GET /reasonList/report	Displays the field name used to order the data that gets returned following a GET call. The default used if nothing gets passed here is to sort based on the professionalId property.
order_mode	string	GET /reasonList/reportWithCount, GET /reasonList/report	Displays the order type that is used to order the data that gets returned following a GET call. Available options are "asc" for ascending and "desc" for descending.
pageNumber	integer	GET /reasonList/reportWithCount, GET /reasonList/report	Works 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 reasons that get returned appear.
pageSize	integer	GET /reasonList/reportWithCount, GET /reasonList/report	Works with the pageNumber parameter to determine how data gets returned following a GET call. The pageSize value represents the number of reasons appearing on each page of class sessions reasons that gets returned.
reasonIdList	integer array	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Should be set as a comma-separated list of the reasonIds connected to the reasons to return following the API call. Only active reasonIds that match any other parameter criteria should return.
reasonIdListToExclude	integer array	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Should be set as a comma-separated list of the reasonIds connected to the reasons that will not return following the API call.
reasonIdListToGetAddOnsFor	integer array	GET /reasonIdList	Should be set as a comma-separated list of the reasonIds to get reason add ons for. This parameter is used to get the reasonIds for the add ons assigned to specific reasons. For instance, say you have a reason of reasonType SERVICE with a reasonId of 12345, and a reason of reasonType CLASS with a reasonId of 67890. If you pass "12345,67890" in the reasonIdListToGetAddOnsFor then the reasonIds that return should be the reasonIds representing the addOns assigned to that SERVICE and CLASS.
reasonGroupIdList	integer array	GET /reasonIdList	Should be set as a comma-separated list of groupIds representing group objects of groupType SERVICE and will return the list of reasonIds that are in the reason group.
reasonTypeList	string array	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Should be set as a comma-separated list of the reasonTypes of the appointments to return following the API call. Acceptable values include: SERVICE, CLASS, COURSE, ADDON, PERSONAL.
searchTerm	string	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	String value which is used to identify only reasons who have a match for that searchTerm in their `reasonDesc`, `internalName`, or `reasonDetail` properties.
staffId	integer	GET /services	Returns an array of services offered by a certain staff member.
staffIdList	integer array	POST /services, GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	For POST /services endpoint - Automatically assigns the reason being created to the staffIds being passed. The staffIdList should be passed as a comma separated list. For GET /reasonIdList and GET /reasonList calls - Should be set as a comma-separated list of professionalIds representing staff objects on your account. Will return only reasonIds that the staff passed in the API call offers.
startDate	string	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Used in conjunction with dateRangeType and endDate parameters. Date should be set in format of YYYY-MM-DD. If all 3 parameters are passed, then the API will only return reasonIds that fall within the defined date range based on the dateRangeType that is being looked for.
statusList	string	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	Should be set as a comma-separated list of the reason statuses connected to the reasons to return following the API call. Can be set as ACTIVE, DEACTIVE, and DELETED. The default used if no value is passed here is ACTIVE.
waitListOnly	boolean	GET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdList	If set to true, only reasons with `allowWaitlist` set to true will return. If you pass false (default), then no check is made on the `allowWaitlist` property.
working	boolean	GET /reasonIdList	Works in conjunction with the staffIdList and locationIdList parameters. If set to true, then only reasonIds that are offered at the passed locationIds and/or by the passed staffIds will return.

Code Block

language	js
title	GET /services
linenumbers	true
collapse	true

[{
	"active": true,
	"allowOnline": true,
	"allowPrePay": false,
	"allowWaitList": false,
    "apptDayMax": null,
    "apptHrMin": null,
	"bufferAfter": null,
    "bufferBefore": null,
    "businessId": null,
    "customWorkSchedule": 0,
	"depositAmount": null,
	"discountedPrice": null,
	"embedCode": null,
	"imageUrl": null,
    "internalDisplayName": null,
	"internalName": null,
	"maxWaitListPerClass": null,
	"modifiedUser": null,
    "numberSessions": null,
	"personal": false,
	"price": 10,
    "privateUrl": null,
	"quota": null,
	"quotaFilled": null,
    "quotaType": null,
    "reasonDesc": null,
    "requiresStaffConfirmation": null,
	"rescheduleType": null,
    "screeningQuestion": null,
	"serviceLocations": null,
	"sortWeight": 0,
    "taxable": false,
    "visitMinutes": null
}]

Code Block

language	js
title	GET /services/{reasonId}
linenumbers	true
collapse	true

{
    "active": true,
    "allowOnline": true,
    "allowPrePay": false,
    "allowWaitList": false,
    "apptDayMax": null,
    "apptHrMin": null,
    "bufferAfter": 5,
    "bufferBefore": 5,
    "businessId": 21345,
    "customWorkSchedule": 0,
    "depositAmount": null,
    "discountedPrice": null,
    "embedCode": null,
    "imageUrl": null,
    "internalDisplayName": "Underwater Basket Weaving",
    "internalName": null,
    "maxWaitListPerClass": null,
    "modifiedUser": "Jane Doe",
    "numberSessions": null,
    "personal": false,
    "price": 10,
    "quota": null,
    "quotaFilled": null,
    "quotaType": null,
    "reasonDesc": "Underwater Basket Weaving",
    "requiresStaffConfirmation": null,
    "rescheduleType": null,
    "screeningQuestion": null,
    "serviceLocations": null,
    "sortWeight": 0,
    "taxable": false,
    "visitMinutes": 60
}

Code Block

language	js
title	GET /services/{reasonId}/serviceStaff
linenumbers	true
collapse	true

[{
	"active": true,
    "businessId": 21345,
    "createdDate": 6678434353778,
    "createdUser": "Jane Doe",
    "description": "Just Jane",
    "modifiedDate": null,
	"modifiedUser": null,
	"price": null,
    "professionalId": 21345,
    "professionalServiceId": 2964486,
    "reasonId": 995563,
    "reasonType": null
}]

Code Block

language	js
title	GET /reasonList/reportWithCount
linenumbers	true
collapse	true

{
    "reasons": [
    {
        "active": true,
        "allowOnline": true,
        "allowPrePay": false,
        "allowWaitList": false,
        "apptDayMax": null,
        "apptHrMin": null,
        "bufferAfter": 5,
        "bufferBefore": 5,
        "businessId": 21345,
        "customWorkSchedule": 0,
        "depositAmount": null,
        "discountedPrice": null,
        "embedCode": null,
        "imageUrl": null,
        "internalDisplayName": "Underwater Basket Weaving",
        "internalName": null,
        "maxWaitListPerClass": null,
        "modifiedUser": "Jane Doe",
        "numberSessions": null,
        "personal": false,
        "price": 10,
        "quota": null,
        "quotaFilled": null,
        "quotaType": null,
        "reasonDesc": "Underwater Basket Weaving",
        "requiresStaffConfirmation": null,
        "rescheduleType": null,
        "screeningQuestion": null,
        "serviceLocations": null,
        "sortWeight": 0,
        "taxable": false,
        "visitMinutes": 60
}],
    "count": 12}

Code Block

language	js
title	GET /reasonList/report
linenumbers	true
collapse	true

[{
    "active": true,
    "allowOnline": true,
    "allowPrePay": false,
    "allowWaitList": false,
    "apptDayMax": null,
    "apptHrMin": null,
    "bufferAfter": 5,
    "bufferBefore": 5,
    "businessId": 21345,
    "customWorkSchedule": 0,
    "depositAmount": null,
    "discountedPrice": null,
    "embedCode": null,
    "imageUrl": null,
    "internalDisplayName": "Underwater Basket Weaving",
    "internalName": null,
    "maxWaitListPerClass": null,
    "modifiedUser": "Jane Doe",
    "numberSessions": null,
    "personal": false,
    "price": 10,
    "quota": null,
    "quotaFilled": null,
    "quotaType": null,
    "reasonDesc": "Underwater Basket Weaving",
    "requiresStaffConfirmation": null,
    "rescheduleType": null,
    "screeningQuestion": null,
    "serviceLocations": null,
    "sortWeight": 0,
    "taxable": false,
    "visitMinutes": 60
}]

Code Block

title	GET /reasonList/reportCount
linenumbers	true
collapse	true

{
    "count": 12
}

Code Block

title	GET /reasonIdList
linenumbers	true
collapse	true

Code Block

language	js
title	POST /services
linenumbers	true
collapse	true

{
	"active": true,
	"allowOnline": true,
	"allowPrePay": false,
	"allowWaitList": false,
    "apptDayMax": null,
    "apptHrMin": null,
	"bufferAfter": 5,
    "bufferBefore": 5,
    "businessId": 43111,
    "customWorkSchedule": 0,
	"depositAmount": null,
	"discountedPrice": null,
	"embedCode": null,
	"imageUrl": null,
    "internalDisplayName": "Pooch primping",
	"internalName": "Pooch primping",
	"maxWaitListPerClass": null,
	"modifiedUser": "Jane Doe",
    "numberSessions": null,
	"personal": false,
	"price": 10,
	"quota": null,
	"quotaFilled": null,
    "quotaType": null,
    "reasonDesc": "Dog grooming",
    "reasonDetail": "<p>We groom your pups!</p>",
    "reasonType": "SERVICE",
    "requiresStaffConfirmation": null,
	"rescheduleType": null,
    "screeningQuestion": null,
	"serviceLocations": null,
	"sortWeight": 0,
    "taxable": false,
    "visitMinutes": 90
}

Code Block

language	js
title	POST /services/{reasonId}/serviceStaff
linenumbers	true
collapse	true

[{
    "active": true,
    "businessId: 21345,
    "createdDate": 4476890812667,
    "createdUser": "Jane Doe",
    "description": null,
    "modifiedDate": 155677422,
    "modifiedUser": "Jane Doe",
    "price": null,
    "professionalId": 86673,
    "professionalServiceId": 2924664,
    "reasonId": 13613,
    "reasonType": null
}]

Code Block

language	js
title	PUT /services/{reasonId}
linenumbers	true
collapse	true

{
	"active": true,
	"allowOnline": true,
	"allowPrePay": false,
	"allowWaitList": false,
    "apptDayMax": null,
    "apptHrMin": null,
	"bufferAfter": null,
    "bufferBefore": null,
    "businessId": 43111,
    "customWorkSchedule": 0,
	"depositAmount": null,
	"discountedPrice": null,
	"embedCode": "<iframe src='http://www.timetap.com/pembed/gty7U88op2C' frameborder='0' width='840' height='500'> </iframe>",
	"imageUrl": null,
    "internalDisplayName": "Underwater Basket Weaving",
	"internalName": null,
	"maxWaitListPerClass": null,
	"modifiedUser": "Jane Doe",
    "numberSessions": null,
	"personal": false,
	"price": 10,
    "privateUrl": "http://www.timetap.com/appts/g0po5JiS"
	"quota": null,
	"quotaFilled": null,
    "quotaType": null,
    "reasonDesc": "Underwater Basket Weaving",
    "requiresStaffConfirmation": null,
	"rescheduleType": null,
    "screeningQuestion": null,
	"serviceLocations": [{serviceLocationId: null, businessId: 21345, reasonId: 153367, locationId: 81125, active: false,},
	"sortWeight": 0,
    "taxable": false,
    "visitMinutes": 60
}

Property name	Type	Required	Description
active	boolean	Yes	Indicates whether or not specified reason should return on GET calls.
allowOnline	boolean		Indicates whether or not the service is bookable on the scheduler or only on the back office.
allowPrePay	boolean		Indicates whether or not the customer will be able to pre-pay for this service through the scheduler if a payment gateway or PayPal is set up.
allowWaitList	boolean		Indicates whether or not the service allows the use of a waitlist.Used on a service-by-service or class-by-class basis.
apptDayMax	integer		Displays as the number of days in the future a client can book with you, this is known as the "Advanced Appointments" feature.
apptHrMin	integer		Displays as how close to the start of an appointment, in hours, a client can book with you. This is also known as the "Latest Appointment" feature.
bufferAfter	integer		Time required after an appointment so appointments can’t be booked back-to-back; set in five minute increments.
bufferBefore	integer		Time required before an appointment so appointments can’t be booked back-to-back; set in five minute increments.
businessId	integer		Provides unique numerical ID for the business that offers the specified service.
customWorkSchedule	integer		Can be set to 0, 1, or 2. This property corresponds to the serviceLocations property when set to either 0 or 2. If 0 the service is available at "All locations", if 2 the service is available at "Select locations", and if 1 the service has a custom work schedule. Only used for reasonType = SERVICE. For more info, see the Service Location API page.
depositAmount	integer		If the specified service has payment settings that include a deposit, this is the size of that deposit.
discountedPrice	string		Calculates any coupons or discounts and displays the new price here.
durationList	array		Can have either a single duration (stored under visitMinutes) or multiple durations the client can choose from. If it has multiple durations, then they are stored as objects in the durationList property. Only used for reasonType = SERVICE.
emailInstructions	string		The first of two free form text fields provided on each reason object used to inject custom instructions for that reason into emails and notifications sent out about it.
emailInstructions2	string		The second of the two free-form text fields described above.
embedCode	string		Provides iframe code that can be used to display scheduler for this service based on address given in reasonDesc; back-end component, users cannot alter.
imageUrl	string		Displays image associated with specified reason. Can be displayed above the reason in the scheduler.
internalDisplayName	string		If reasonDesc is filled out but internalName is empty, internalDisplayName would be the same as the reasonDesc; if the internalName filled out, the internalDisplayName would be the same as the internalName.
internalName	string		Displays as name that staff members see for the specified service.
maxWaitListPerClass	string		Displays the number of clients who are allowed to join a waitlist on a per class session basis. Only used for reasonType = CLASS, and only applicable if the allowWaitList property is set to true.
modifiedUser	string		Displays the username of the user who last modified the specified service.
numberSessions	string		Displays the number of sessions per course set. Only used for reasonType = COURSE.
personal	boolean		Displays whether or not the service is a personal reason; if set to true then the service will only be visible to staff members who are logged into the dashboard.
price	float		Provides the price of specified service. If the service has a price associated with it but does not have a depositAmount, customers pay full price for the service up front; if the service has a price and a deposit associated with it, customers only pay the deposit amount for the service up front with the rest of the payment being due at the time of the appointment.
privateUrl	string		Displays the URL of the private booking page for the specified reason. No other reasons can be booked at the private URL except the reason to which the private URL belongs.
quota	integer		Provides the max number of clients that can book the reason over a given period of time.
quotaFilled	integer		Displays how many spaces of the quota have been used for the given service based on the time frame (see quotaType below). This is filled in on the backend if the quota property is filled.
quotaType	string		Provides time frame as used by quota property; can be one of five values: lifetime, year, month, week, or day.
reasonDesc	string		Displays as the name of specified reason.
reasonDetail	string		Provides a description of specified reason; displays under name of that reason in scheduling flow.
reasonId	integer	Yes, for PUT calls	Provides unique numerical ID for specified service.
reasonType	string		Displays the type of appointment. Has acceptable values SERVICE, CLASS, COURSE, and PERSONAL.
requiresStaffConfirmation	boolean		Indicates whether or not when a client books a service the staff person will first receive an email asking him or her whether they want to accept the appointment or not instead of automatically confirming the appointment when a client books a service.
rescheduleType	string		Provides the type of rescheduling protocol allowed by a business. Can be set to one of three values: s, f, or n. s means "Strict" and only allows rescheduling of equivalent sessions, f means "Flexible" and allows rescheduling of any sessions, and n means "Not allowed" to reschedule sessions.
screeningQuestion	object		Displays a screening question for specified reason that a client gets prompted to "pass" before being shown available times.
serviceLocations	array		Corresponds with customWorkSchedule when it is set to either 0 or 2, and designates at what locations specified service is offered. Only used for reasonType = SERVICE.
sortWeight	integer		In what order in a list of services the specified service appears; a value of 0 has highest priority and is displayed first.
taxable	boolean		Indicates whether or not this service is taxed. If set to true, when the service is booked and an invoice is created per the payment settings method, then whatever tax is stored in payment settings is applied.
visitMinutes	integer		Displays as number of minutes designated for specified service.

Versions Compared

Old Version 107

New Version 108

Key

Services API Endpoints

Services API Parameters

Services API Responses

Services Object Values