Page Comparison

Anchor

	topOfPage
	topOfPage

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

Staff are made accessible to all users on a business's account, but a user will only be able to access his or her own staff's information and book appointments for him- or herself unless he or she is an admin or a location super user.

Info

title	On this page

Table of Contents

These are the endpoints that are available under the /staff path, which lists all the different staff members you have added to your business using TimeTap.

Endpoint

Description

GET /staff

Returns all staff objects on an account in array format.

GET /staff/{professionalId}

Returns a JSON object for the specified staff person.

GET /staff/{professionalId}/serviceStaff

Returns the objects of all services and classes on the account in array format.

GET /staffList/reportWithCount

Returns an object that contains a list of staff along with a count of the total number of staff that match the parameters passed with the call.

GET /staffList/report

Returns an object that contains a list of staff that match the parameters passed with the call.

GET /staffList/reportCount

Returns a count object that provides the number of staff that match the parameters passed with the call.

GET /staffIdList

Returns an object that contains list of the professional IDs for the locations that match the parameters passed with the call.

POST /staff

Creates a new staff object on an account.

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

For these calls, you need to pass a staff 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 staff object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

POST /staff/{professionalId}

Updates an existing staff object on an account.

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

For these calls, you need to pass a staff 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 staff object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

POST /staff/{professionalId}/serviceStaff

Updates the list of services/class that a staff member can offer. Be sure to set the active property on each service/class object in the array to true or false depending on whether the staff member offers that service/class.

Request body/payload: Must pass the array of services/classes you got from the respective GET call in the request body/payload.

DELETE /staff/{{professionalId}}

Removes a staff object by setting its active property to false. Requires a JSON POST body with values signifying if they should cancel any open appointments that staff member has and if it should send those affected clients an email explaining why the appointments were cancelled, along with a string value of the personalized message to send in those emails. See example below.

Code Block
{ "cancelOpenAppts": true, "sendClientEmail": true, "cancelReason": "{Reason for cancelling staff member's appointments}" }

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
acceptAppointments	boolean	GET /staff, GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	If set to true, only staff members who have the acceptAppointments property on their staff object set to true will return.
dateRangeType	string	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Can be set to a value of 'createdDate' or 'modifiedDate' and works with startDate and endDate parameters to filter staff returned following the API call based on those properties.
endDate	string	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a string formatted YYYY-MM-DD and works with the dateRangeType parameter to filter staff returned following the API call.
locationId	integer	GET /staff	Should be set as a comma-separated list of all staff that have working hours at specified location.
locationIdList	integer array	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a comma-separated list of locationIds and will only return staff who have access to the corresponding locations.
locationGroupIdList	integer array	GET /staff	Can be used when calling staff members from multiple locationIds that can be passed as a comma-separated list.
onlyAccessAllLocations	boolean	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	If set to true, it will only return staff whose security roles give access to all locations.
order_field	string	GET /staffList/reportWithCount, GET /staffList/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 /staffList/reportWithCount, GET /staffList/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.
reasonIdList	integer array	POST /staff, GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Automatically assigns the staff being created to the reasonIds being passed. The reasonIdList should be passed as a comma separated list.
searchTerm	string	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Searches the following staff object properties to see if there is any substring match - description, userName, cellPhone, fullName, emailFooter, internalName, emailInstructions, emailInstructions2.
securityRoleIdList	integer array	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a comma-separated list of security role IDs and will only return staff who are assigned to those security roles.
staffIdList	integer array	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a comma-separated list of staff IDs and will only return those staff that match those IDs.
staffIdListToExclude	integer array	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a comma-separated list of staff IDs and will only return those staff that do not match those IDs.
startDate	string	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a string formatted YYYY-MM-DD and works with the dateRangeType parameter to filter staff returned following the API call.
statusList	string	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a comma-separated list of available staff statuses (right now there is only support for 3 staff statuses: ACTIVE, DEACTIVE, DELETED). The default used if no value is passed here is ACTIVE.
userNameList	string	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	Should be set as a comma-separated list of usernames and will only return staff whose usernames match the values passed.
working	boolean	GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdList	If set to true, will only return staff who have working hours set up - works in conjunction with the locationIdList and reasonIdList parameters if those are filled in to only return staff that are working at those locationIds and offer those reasonIds.

The objects below represent the minimum viable objects to pass that are needed to create or update a staff object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.

Code Block

language	js
title	POST /staff
linenumbers	true
collapse	true

{
    "acceptAppointments": true,
    "emailFooter": "(HTML text of email footer)",
    "fullName": "test staff",
    "locationAccessList": [{Array of locations objects for locations that can be accessed by staff member - for more info, see Locations API page}],
    "locationIdAccessList": [81181],
    "locationList": [{Array of locations objects staff member can work at - for more info, see Locations API page}],
    "newApptSms": false,
    "securityRoleId": "3",
    "sendWelcomeMessage": false,
    "timeZone": {Timezone object for timezone of staff - for more info, see Timezones API page},
    "userName": "123teststaff"
}

Code Block

language	js
title	POST /staff/{professionalId}
linenumbers	true
collapse	true

{
    "acceptAppointments": true,
    "active": true,
    "allOrNoneSelectLocations": {value: "select", label: "Select Locations"},
    "allowOnline": true,
    "businessId": 43111,
    "changePasswordNextLogin": false,
    "clockedIn": null,
    "createdDate": 1533913629597,
    "currentStationName": null,
    "email": null,
    "emailFooter": "(Html text of email footer)",
    "emailInstructions": null,
    "embedCode": "<iframe src='https://www.timetap.com/pembed/l0zYfY99lFg' frameborder='0' width='840' height='500'> </iframe>",
    "excludeEmailCategoryIdList": null,
    "firstDayOfWeek": null,
    "fullName": "Mr. Jones",
    "googleSyncActive": false,
    "googleSyncPeriod": "",
    "guestHashEnabled": false,
    "imageUrl": null,
    "internalDisplayName": "Mr. Jones",
    "internalName": "Jonesy",
    "lastLoginDate": null,
    "locale": null,
    "localeObj": null,
    "locationIdAccessList": [282639, 319495],
    "locationsWithSchedule": null,
    "mobilePhone": null,
    "newApptSms": false,
    "originalSecurityRoleId": 3,
    "phone": null,
    "privateUrl": "https://www.timetap.com/appts/l0zYfY99lFg",
    "professionalId": 154514,
    "salesforceUserId": null,
    "securityRoleId": 3,
    "skypeId": null,
    "sortWeight": 0,
    "staffProfile": null,
    "staffRateLevel": "experienced",
    "status": "DEACTIVE",
    "syncStaffIdList": null,
    "syncStaffList": null,
    "syncStaffUserName": null,
    "timeZone": {Timezone object for timezone of staff - for more info, see Timezones API page},
    "userName": "MRJONES11"
}

Code Block

language	js
title	GET /staff
linenumbers	true
collapse	true

[{
    "acceptAppointments": null,
	"active": true,
    "allowOnline": true,
    "businessId": null,
    "changePasswordNextLogin": false,
    "createdDate": 1525113573000,
    "currentStationName": null,
    "email": noreply@email.com",
    "emailFooter": "<strong>You can contact us at:</strong><br/>%STAFF_FULLNAME%<br/>%BUSINESS_NAME%<br/>%STAFF_EMAIL%<br/>%STAFF_MOBILE%",
    "excludeEmailCategoryIdList": null,
    "firstDayOfWeek": 0,
    "fullName": "Mr. Biscuits",
    "googleSyncActive": false,
    "guestHashEnabled": "",
    "imageUrl": null,
    "internalDisplayName": "Mr. Biscuits",
    "internalName": null,
    "lastLoginDate": null,
    "locale": null,
    "locationIdAccessList": null,
    "locationsWithSchedule": null,
    "mobilePhone": null,
    "newApptSms": false,
    "privateUrl": null,
	"professionalId": 80891,
    "salesforceUserId": null,
    "securityRoleId": 4,
    "skypeId": null,
    "sortWeight": 0,
    "staffProfile": null,
    "syncStaffIdList": null,
    "syncStaffList": null,
    "syncStaffUserName": null,
    "timeZone": {Timezone object for timezone of staff-see timezones API page},
	"userName": "TRUBISKY13"
}]

Code Block

language	js
title	GET /staff/{professionalId}
linenumbers	true
collapse	true

{
    "acceptAppointments": true,
	"active": true,
    "allowOnline": true,
    "businessId": 21345,
    "changePasswordNextLogin": false,
    "createdDate": 1522268786000,
    "currentStationName": null,
    "email": "noreply@email.com",
    "emailFooter": "<strong>You can contact us at:</strong><br/>%STAFF_FULLNAME%<br/>%BUSINESS_NAME%<br/>%STAFF_EMAIL%<br/>%STAFF_MOBILE%",
    "embedCode": "<iframe src='http://www.timetap.com/pembed/q0ZQf1LYuB' frameborder='0' width='840' height='500'> </iframe>,
    "excludeEmailCategoryIdList": null,
    "firstDayOfWeek": null,
    "fullName": "Dr. J",
    "googleSyncActive": false,
    "guestHashEnabled": "",
    "imageUrl": null,
    "internalDisplayName": "Dr. J",
    "internalName": null,
    "lastLoginDate": null,
    "locale": null,
    "locationIdAccessList": [319495,  157670, 87877, 282639],
    "mobilePhone": null,
    "newApptSms": false,
    "privateUrl": "http://www.timetap.com/appts/q0ZQf1lYu0",
	"professionalId": 81988,
    "salesforceUserId": null,
    "securityRoleId": 3,
    "skypeId": null,
    "sortWeight": 0
    "staffProfile": null,
    "syncStaffIdList": null,
    "syncStaffUserName": null,
    "timeZone": {Timezone object for timezone of staff-see timezones API page},
	"userName": "DR.J54"
}

Code Block

language	js
title	GET /staff/{professionalId}/serviceStaff
linenumbers	true
collapse	true

[{
	"active": true,
    "businessId": 21345,
    "createdDate": 1522268786000,
    "createdUser": "Jane_Doe"
    "description": "Class Name"
    "modifiedDate": 1522268786021,
    "modifiedUser": "Jane_Doe"
    "price": null
	"professionalId": 77777,
    "professionalServiceId": 2005000
    "reasonId": 153346
    "reasonType": "CLASS"
}]

Code Block

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

{
    "staff": [
    {
        "acceptAppointments": null,
    	"active": true,
        "allowOnline": true,
        "businessId": null,
        "changePasswordNextLogin": false,
        "createdDate": 1525113573000,
        "currentStationName": null,
        "email": noreply@email.com",
        "emailFooter": "<strong>You can contact us at:</strong><br/>%STAFF_FULLNAME%<br/>%BUSINESS_NAME%<br/>%STAFF_EMAIL%<br/>%STAFF_MOBILE%",
        "excludeEmailCategoryIdList": null,
        "firstDayOfWeek": 0,
        "fullName": "Mr. Biscuits",
        "googleSyncActive": false,
        "guestHashEnabled": "",
        "imageUrl": null,
        "internalDisplayName": "Mr. Biscuits",
        "internalName": null,
        "lastLoginDate": null,
        "locale": null,
        "locationIdAccessList": null,
        "locationsWithSchedule": null,
        "mobilePhone": null,
        "newApptSms": false,
        "privateUrl": null,
    	"professionalId": 80891,
        "salesforceUserId": null,
        "securityRoleId": 4,
        "skypeId": null,
        "sortWeight": 0,
        "staffProfile": null,
        "syncStaffIdList": null,
        "syncStaffList": null,
        "syncStaffUserName": null,
        "timeZone": {Timezone object for timezone of staff-see timezones API page},
	    "userName": "TRUBISKY13"
}]

Code Block

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

[{
    "acceptAppointments": true,
	"active": true,
    "allowOnline": true,
    "businessId": 21345,
    "changePasswordNextLogin": false,
    "createdDate": 1522268786000,
    "currentStationName": null,
    "email": "noreply@email.com",
    "emailFooter": "<strong>You can contact us at:</strong><br/>%STAFF_FULLNAME%<br/>%BUSINESS_NAME%<br/>%STAFF_EMAIL%<br/>%STAFF_MOBILE%",
    "embedCode": "<iframe src='http://www.timetap.com/pembed/q0ZQf1LYuB' frameborder='0' width='840' height='500'> </iframe>,
    "excludeEmailCategoryIdList": null,
    "firstDayOfWeek": null,
    "fullName": "Dr. J",
    "googleSyncActive": false,
    "guestHashEnabled": "",
    "imageUrl": null,
    "internalDisplayName": "Dr. J",
    "internalName": null,
    "lastLoginDate": null,
    "locale": null,
    "locationIdAccessList": [319495,  157670, 87877, 282639],
    "mobilePhone": null,
    "newApptSms": false,
    "privateUrl": "http://www.timetap.com/appts/q0ZQf1lYu0",
	"professionalId": 81988,
    "salesforceUserId": null,
    "securityRoleId": 3,
    "skypeId": null,
    "sortWeight": 0
    "staffProfile": null,
    "syncStaffIdList": null,
    "syncStaffUserName": null,
    "timeZone": {Timezone object for timezone of staff-see timezones API page},
	"userName": "DR.J54"
}]

Code Block

title	GET /staffList/reportCount
linenumbers	true
collapse	true

{
    "count": 8
}

Code Block

title	GET /staffIdList
linenumbers	true
collapse	true

Code Block

language	js
title	POST /staff
linenumbers	true
collapse	true

{
    "acceptAppointments": true,
	"active": true,
    "allowOnline": true,
    "businessId": 21345,
    "changePasswordNextLogin": false,
    "createdDate": 1522268786000,
    "currentStationName": null,
    "email": null,
    "emailFooter": null,
    "emailInstructions": null,
    "excludeEmailCategoryIdList": null,
    "firstDayOfWeek": 0,
    "fullName": "Jane Doe"
    "googleSyncActive": false,
    "guestHashEnabled": "",
    "imageUrl": null,
    "internalDisplayName": null,
    "internalName": "Jane Doe",
    "lastLoginDate": 156773877456,
    "locale": "en-US",
    "locationIdAccessList": null,
    "locationsWithSchedule": null,
    "mobilePhone": "5551234",
    "newApptSns": false,
    "privateUrl": null,
	"professionalId": 21345,
    "salesforceUserId": null,
    "securityRoleId": 3,
    "skypeId": null,
    "sortWeight": 0,
    "staffProfile": null,
    "syncStaffIdList": null,
    "syncStaffList": null,
    "syncStaffUserName": null,
    "timeZone": {Timezone object for timezone of staff-see timezones API page},
	"userName": null
}

Code Block

language	js
title	POST /staff/{professionalId}
linenumbers	true
collapse	true

{
    "acceptAppointments": true,
    "active": true,
    "allowOnline": true,
    "businessId": 43111,
    "changePasswordNextLogin": false,
    "clockedIn": null,
    "createdDate": 1533913629597,
    "currentStationName": null,
    "email": null,
    "emailFooter": "(HTML text of email footer)",
    "emailInstructions": null,
    "embedCode": "<iframe src='https://www.timetap.com/pembed/l0zYfY99lFg' frameborder='0' width='840' height='500'> </iframe>",
    "excludeEmailCategoryIdList": null,
    "firstDayOfWeek": null,
    "fullName": "Mr. Jones",
    "googleSyncActive": false,
    "googleSyncPeriod": "",
    "guestHashEnabled": false,
    "imageUrl": null,
    "internalDisplayName": "Mr. Jones",
    "internalName": "Jonesy",
    "lastLoginDate": null,
    "locale": null,
    "locationIdAccessList": [282639, 319495],
    "locationsWithSchedule": null,
    "mobilePhone": null,
    "newApptSms": false,
    "phone": null,
    "privateUrl": "https://www.timetap.com/appts/l0zYfY99lFg",
    "professionalId": 154514,
    "salesforceUserId": null,
    "securityRoleId": 3,
    "skypeId": null,
    "sortWeight": 0,
    "staffProfile": null,
    "staffRateLevel": "experienced",
    "status": "DEACTIVE",
    "syncStaffIdList": null,
    "syncStaffList": null,
    "syncStaffUserName": null,
    "timeZone": {Timezone object for timezone of staff},
    "userName": "MRJONES11"
}

Property name	Type	Required	Writable	Description
acceptAppointments	boolean		Yes	Indicates whether or not the specified staff person is accepting appointments.
active	boolean	Yes		Indicates whether or not the specified staff person should return on GET calls.
allowOnline	boolean		Yes	Indicates whether or not the specified staff person is bookable on the scheduler or only on the back office.
businessId	integer	Yes		Provides a unique numerical ID of the business to which the staff person belongs.
changePasswordNextLogin	boolean		Yes	Indicates whether or not the Prompt to Change Password box is checked.
clockedIn	boolean		Yes	If your business uses the clock in screen, this value will indicate whether or not the specified staff person is currently clocked in and taking appointments from the queue of checked-in clients.
createdDate	integer			Displays as the date the specified staff person was added to your business account, in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
currentStationName	string		Yes	Displays if the specified staff person is clocked in using the clockedIn property described above and have clocked in to a specific station.
email	string		Yes	Displays as the email address for the specified staff person.
emailFooter	string		Yes	This footer can be included in any emails sent on behalf of the specified staff person by including the tag "STAFF_SIGNATURE", and displays as a personalized signature for that staff person.
emailInstructions	string		Yes	Displays as what is saved as the specified staff's email instructions.
emailInstructions2	string		Yes	Displays as what is saved as the specified staff's additional email instructions.
embedCode	string			Provides iframe code that can be used to display scheduler for the specified staff person based on the address provided in staff description - back-end component, users cannot alter.
excludeEmailCategoryIdList	array		Yes	Displays a list of email category IDs the specified staff person elects not to receive.
firstDayOfWeek	integer		Yes	Acts as a 0-6 scale that determines what day begins the specified staff person's work week, where 0=Sunday, 1=Monday, etc.
fullName	string	Yes	Yes	Displays as the specified staff’s first and last name.
googleSyncActive	boolean		Yes	Indicates whether or not the specified staff person has an external calendar sync set up. This works for any external calendars, not just Google Calendars.
guestHashEnabled	boolean		Yes	Indicates whether or not the specified staff person has had a guest landing page set up for them to enter their hours of availability.
imageUrl	string		Yes	Displays as the URL of the specified staff person's profile picture.
internalDisplayName	string		Yes	If fullName is filled out but internalName is empty, internalDisplayName would be the same as the fullName - if the internalName is not empty, the internalDisplayName would be the same as the internalName.
internalName	string		Yes	Displays as name that other staff members see for the specified staff person.
lastLoginDate	string			Displays as the date that specified staff person last logged in, in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. .
locale	string			Displays as general preferred country and language of specified staff person; by default this value is read from their browser settings - for more info, see Locale API page.
locationIdAccessList	array		Yes	Displays as an array of the location objects a staff person can access to add working hours and see appointments, and their security role ID will determine whether they only see their own appointments or if they are able to see other staff members' appointments at these locations. The "user" security role, which is securityRoleId=3, would be the only default security role that would not be able to see other staff members' appointments at the locations to which they have been given access.
mobilePhone	string		Yes	Displays as mobile phone number of the specified staff person where they will receive text message alerts if the newApptSms property on their account is set to true.
newApptSms	boolean		Yes	Indicates whether or not the specified staff person elects to receive text messages for new appointment bookings.
privateUrl	string			Displays as the URL of specified staff person's private scheduling page.
professionalId	integer	Yes, for POST /staff/{professionalId} calls		Provides a unique numerical ID of the specified staff person. Can be used to look that staff person up in our database.
salesforceUserId	string		Yes	Only to be filled if the specified staff person has a salesforce integration set up, this is the user ID linked to the salesforce account that they integrated to TimeTap. Salesforce integration is included in TimeTap's Business level plan.
securityRoleId	integer	Yes	Yes	This would either be one of our default security roles (security role IDs of 1-6), or a custom security role ID if they are a Business plan account that has created custom security roles for their users. The securityRoleId determines the staff members access privileges when he/she logs into TimeTap.
skypeId	string		Yes	Displays as the specified staff person's Skype ID and can be included in emails and text messages by using the tag %STAFF_SKYPE_ID%.
sortWeight	integer		Yes	Affects the order in which different staff members at a business location are displayed to users.
staffProfile	string		Yes	Displays as the personal bio of the specified staff person that can display under their name in the scheduler - can be merged to email templates and messaging with the tag %STAFF_DESCRIPTION%.
syncStaffIdList	array		Yes	Only usable by accounts linked via our enterprise parent-child setup method. If you have two child accounts that share staff and you want to sync those two accounts' staff members calendars so they don't get double booked, you can provide a syncStaffUserName, and any staff from the child accounts that also have that syncStaffUserName will be synced with this staff. This property will fill in as an array of staffIds that have the same syncStaffUserName.
syncStaffUserName	string		Yes	Set to a string value that could potentially be shared with other staff members across your child account. If so, then all calendars will be blocked when staff gets booked on one child account.
timeZone	object			Displays the timezone the specified client's account is set to; by default is set to null so that the timezone of the location and client is used - for more info, see Timezones API page.
userName	string	Yes	Yes	Displays as the specified staff person's username.

Versions Compared

Old Version 107

New Version 108

Key

Staff API Endpoints

Staff API Parameters

Staff API Request Body/Payloads

Staff API Responses

Staff Object Values