Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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
titleOn this page

Table of Contents





Staff API Endpoints


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}/serviceStaffReturns the objects of all services and classes on the account in array format. 
GET /staffList/reportWithCountReturns 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/reportReturns an object that contains a list of staff that match the parameters passed with the call.
GET /staffList/reportCountReturns a count object that provides the number of staff that match the parameters passed with the call.
GET /staffIdListReturns 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}"
}






Staff API Parameters

Data points passed on in the request URL portion of the API call that are used to filter the data being requested. 

Parameter

TypeEndpoints to be used with

Description

acceptAppointments

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

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

endDatestringGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListShould be set as a string formatted YYYY-MM-DD and works with the dateRangeType parameter to filter staff returned following the API call.
locationIdintegerGET /staffShould be set as a comma-separated list of all staff that have working hours at specified location.
locationIdListinteger arrayGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListShould be set as a comma-separated list of locationIds and will only return staff who have access to the corresponding locations.
locationGroupIdListinteger arrayGET /staffCan be used when calling staff members from multiple locationIds that can be passed as a comma-separated list.
onlyAccessAllLocationsbooleanGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListIf set to true, it will only return staff whose security roles give access to all locations.
order_fieldstringGET /staffList/reportWithCount, GET /staffList/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 /staffList/reportWithCount, GET /staffList/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.
reasonIdListinteger arrayPOST /staff, GET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListAutomatically assigns the staff being created to the reasonIds being passed. The reasonIdList should be passed as a comma separated list.
searchTermstringGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListSearches the following staff object properties to see if there is any substring match - description, userName, cellPhone, fullName, emailFooter, internalName, emailInstructions, emailInstructions2.
securityRoleIdListinteger arrayGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListShould be set as a comma-separated list of security role IDs and will only return staff who are assigned to those security roles.
staffIdListinteger arrayGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListShould be set as a comma-separated list of staff IDs and will only return those staff that match those IDs.
staffIdListToExcludeinteger arrayGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListShould be set as a comma-separated list of staff IDs and will only return those staff that do not match those IDs.
startDatestringGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListShould be set as a string formatted YYYY-MM-DD and works with the dateRangeType parameter to filter staff returned following the API call.
statusListstringGET /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.

userNameListstringGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListShould be set as a comma-separated list of usernames and will only return staff whose usernames match the values passed.
workingbooleanGET /staffList/reportWithCount, GET /staffList/report, GET /staffList/reportCount, GET /staffIdListIf 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.





Staff API Request Body/Payloads


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
languagejs
titlePOST /staff
linenumberstrue
collapsetrue
{
    "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
languagejs
titlePOST /staff/{professionalId}
linenumberstrue
collapsetrue
{
    "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"
}





Staff API Responses


Code Block
languagejs
titleGET /staff
linenumberstrue
collapsetrue
[{
    "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
languagejs
titleGET /staff/{professionalId}
linenumberstrue
collapsetrue
{
    "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
languagejs
titleGET /staff/{professionalId}/serviceStaff
linenumberstrue
collapsetrue
[{
	"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
languagejs
titleGET /staffList/reportWithCount
linenumberstrue
collapsetrue
{
    "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
languagejs
titleGET /staffList/report
linenumberstrue
collapsetrue
[{
    "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
titleGET /staffList/reportCount
linenumberstrue
collapsetrue
{
    "count": 8
}


Code Block
titleGET /staffIdList
linenumberstrue
collapsetrue
[
    80891,
    81651,
    81155,
    81988,
    298660,
    302120,
    77961,
    154514
]


Code Block
languagejs
titlePOST /staff
linenumberstrue
collapsetrue
{
    "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
languagejs
titlePOST /staff/{professionalId}
linenumberstrue
collapsetrue
{
    "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"
}





Staff Object Values


Property nameTypeRequiredWritableDescription
acceptAppointmentsboolean
YesIndicates whether or not the specified staff person is accepting appointments.
activebooleanYes
Indicates whether or not the specified staff person should return on GET calls.
allowOnlineboolean
YesIndicates whether or not the specified staff person is bookable on the scheduler or only on the back office.
businessIdintegerYes
Provides a unique numerical ID of the business to which the staff person belongs.
changePasswordNextLoginboolean
YesIndicates whether or not the Prompt to Change Password box is checked.
clockedInboolean
YesIf 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.
createdDateinteger

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. 
currentStationNamestring
YesDisplays if the specified staff person is clocked in using the clockedIn property described above and have clocked in to a specific station.
emailstring
YesDisplays as the email address for the specified staff person.
emailFooterstring
YesThis 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.
emailInstructionsstring
YesDisplays as what is saved as the specified staff's email instructions.
emailInstructions2string
YesDisplays as what is saved as the specified staff's additional email instructions.
embedCodestring

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.
excludeEmailCategoryIdListarray
YesDisplays a list of email category IDs the specified staff person elects not to receive.
firstDayOfWeekinteger
YesActs 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

YesYes

Displays as the specified staff’s first and last name. 

googleSyncActiveboolean
YesIndicates whether or not the specified staff person has an external calendar sync set up. This works for any external calendars, not just Google Calendars.
guestHashEnabledboolean
YesIndicates whether or not the specified staff person has had a guest landing page set up for them to enter their hours of availability. 
imageUrlstring
YesDisplays as the URL of the specified staff person's profile picture.
internalDisplayNamestring
YesIf 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.
internalNamestring
YesDisplays as name that other staff members see for the specified staff person.
lastLoginDatestring

Displays as the date that specified staff person last logged in, in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. .
localestring

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. 
locationIdAccessListarray
YesDisplays 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.
mobilePhonestring
YesDisplays 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.
newApptSmsboolean
YesIndicates whether or not the specified staff person elects to receive text messages for new appointment bookings.
privateUrlstring

Displays as the URL of specified staff person's private scheduling page.
professionalIdintegerYes, 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.
salesforceUserIdstring
YesOnly 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.
securityRoleIdintegerYesYesThis 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. 
skypeIdstring
YesDisplays as the specified staff person's Skype ID and can be included in emails and text messages by using the tag %STAFF_SKYPE_ID%.
sortWeightinteger
YesAffects the order in which different staff members at a business location are displayed to users.
staffProfilestring
YesDisplays 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%. 
syncStaffIdListarray
YesOnly 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.
syncStaffUserNamestring
YesSet 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.
timeZoneobject

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

YesYes

Displays as the specified staff person's username.