Services

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.

On this page




Services API Endpoints

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}/serviceStaffReturns 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}/quotaReturns 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/reportWithCountReturns 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/reportReturns an object that contains a list of reasons that match the parameters passed with the call.
GET /reasonList/reportCountReturns a count object that provides the number of reasons that match the parameters passed with the call.
GET /reasonIdListReturns 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.




Services API Parameters

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

TypeEndpoints to be used with

Description

addOnReasonIdListstring arrayGET /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) .

calendarIdListinteger array GET /reasonIdListShould be set as a comma-separated list of the calendarIds which will then return a unique set of reasonIds assigned to passed calendarId parameter.
classesOnlybooleanGET /servicesIf set to true, only reasons of reasonType = CLASS will return. If passed as false, only reasons with a different reasonType will return.
datestringGET /services/{reasonId}/quotaShould be set as the date that you want to see a services' quota for.
dateRangeTypestringGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListUsed 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.
endDatestringGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListUsed 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.
excludeAddOnsbooleanGET /reasonIdListIf 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.
excludeClassesbooleanGET /servicesIf 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.
excludePersonalbooleanGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListIf set to true, will prevent reasons of reasonType = PERSONAL from returning. 
includePersonalintegerGET /servicesCan 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.
locationGroupIdListinteger arrayGET /reasonIdListIf 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

stringGET /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.

locationIdListinteger arrayGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListShould be set as a comma-separated list of locationIds and will only return reasonIds that are bookable at the passed locationIds.
onlyAddOnsbooleanGET /reasonIdListIf 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.
onlyPersonalbooleanGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListIf set to true, will only return reasons of reasonType = PERSONAL.
order_fieldstringGET /reasonList/reportWithCount, GET /reasonList/reportDisplays 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_modestringGET /reasonList/reportWithCount, GET /reasonList/reportDisplays 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.
pageNumberintegerGET /reasonList/reportWithCount, GET /reasonList/reportWorks 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.
pageSizeintegerGET /reasonList/reportWithCount, GET /reasonList/reportWorks 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 reasons that gets returned.
reasonIdListinteger arrayGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListShould 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.
reasonIdListToExcludeinteger arrayGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListShould be set as a comma-separated list of the reasonIds connected to the reasons that will not return following the API call.
reasonIdListToGetAddOnsForinteger arrayGET /reasonIdListShould 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.
reasonGroupIdListinteger arrayGET /reasonIdListShould 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.
reasonTypeListstring arrayGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListShould 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.
searchTermstringGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListString value which is used to identify only reasons who have a match for that searchTerm in their reasonDesc, internalName, or reasonDetail properties.
staffIdintegerGET /servicesReturns an array of services offered by a certain staff member.
staffIdListinteger arrayPOST /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.

startDatestringGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListUsed 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.
statusListstringGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListShould 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. 
waitListOnlybooleanGET /reasonList/reportWithCount, GET /reasonList/report, GET /reasonList/reportCount, GET /reasonIdListIf 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.
workingbooleanGET /reasonIdListWorks 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.




Services API Responses

GET /services
[{
	"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
}]
GET /services/{reasonId}
{
    "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
}
GET /services/{reasonId}/serviceStaff
[{
	"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
}]
GET /reasonList/reportWithCount
{
    "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}
GET /reasonList/report
[{
    "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
}]
GET /reasonList/reportCount
{
    "count": 12
}
GET /reasonIdList
[
    240094,
    484698,
    175877,
    240127,
    546559,
    436103,
    159330,
    255109,
    255178,
    153346,
    516205,
    434637
]
POST /services
{
	"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
}
POST /services/{reasonId}/serviceStaff
[{
    "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
}]
PUT /services/{reasonId}
{
	"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
}




Services Object Values

Property nameTypeRequiredDescription

active

boolean

Yes

Indicates whether or not specified reason should return on GET calls. 

allowOnlineboolean
Indicates whether or not the service is bookable on the scheduler or only on the back office.
allowPrePayboolean
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.
allowWaitListboolean

Indicates whether or not the service allows the use of a waitlist.Used on a service-by-service or class-by-class basis.

apptDayMaxinteger
Displays as the number of days in the future a client can book with you, this is known as the "Advanced Appointments" feature.
apptHrMininteger
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.
bufferAfterinteger
Time required after an appointment so appointments can’t be booked back-to-back; set in five minute increments.
bufferBeforeinteger
Time required before an appointment so appointments can’t be booked back-to-back; set in five minute increments.
businessIdinteger
Provides unique numerical ID for the business that offers the specified service.
customWorkScheduleinteger
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.
depositAmountinteger
If the specified service has payment settings that include a deposit, this is the size of that deposit.
discountedPricestring
Calculates any coupons or discounts and displays the new price here.
durationListarray
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.
emailInstructionsstring
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. 
emailInstructions2string
The second of the two free-form text fields described above.
embedCodestring
Provides iframe code that can be used to display scheduler for this service based on address given in reasonDescback-end component, users cannot alter.
imageUrlstring
Displays image associated with specified reason. Can be displayed above the reason in the scheduler.
internalDisplayNamestring
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.
internalNamestring
Displays as name that staff members see for the specified service.
maxWaitListPerClassstring
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.
modifiedUserstring
Displays the username of the user who last modified the specified service.
numberSessionsstring
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.

privateUrlstring
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.
quotainteger
Provides the max number of clients that can book the reason over a given period of time.
quotaFilledinteger
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.
quotaTypestring
Provides time frame as used by quota property; can be one of five values: lifetime, year, month, week, or day.
reasonDescstring
Displays as the name of specified reason.
reasonDetailstring
Provides a description of specified reason; displays under name of that reason in scheduling flow.
reasonIdintegerYes, for PUT callsProvides unique numerical ID for specified service. 
reasonTypestring
Displays the type of appointment. Has acceptable values SERVICE, CLASS, COURSE, and PERSONAL. 
requiresStaffConfirmationboolean
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.
rescheduleTypestring
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. 
screeningQuestionobject
Displays a screening question for specified reason that a client gets prompted to "pass" before being shown available times.
serviceLocationsarray
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.

visitMinutesinteger
Displays as number of minutes designated for specified service.