Staff
- Lucy Barber (Unlicensed)
- Joel Kearney
- Joel Morgan Kearney (Unlicensed)
- Matt Bryant (Unlicensed)
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. {
"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.
| Property name | Type | Required | Writable | Description |
|---|---|---|---|---|
| acceptAppointments | boolean | Yes | Indicates whether or not the specified staff person is accepting appointments. | |
| accountLocked | boolean | Yes | Indicates whether or not the specified staff's account is locked. | |
| active | boolean | Yes | Indicates whether or not the specified staff person should return on GET calls. | |
| addnlVirtualRoomUrls | string | Yes | Provides a list of all additional virtual room URLs the specified staff has associated with themself. | |
| 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. | ||
| createdUser | string | Displays the username of user who created the specified staff's account. | ||
| 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. | |
| 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. | |
| googleSyncPeriod | string | Displays as the period between Google syncs that the specified staff has. | ||
| 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 | Yes | 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. | |
| locationGroupIdList | array | Yes | Displays as an array of the IDs of the location groups whose locations a staff person can access to add working hours and see appointments. | |
| locationIdAccessList | array | Yes | Displays as an array of the IDs of the locations 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. | |
| locationsWithSchedule | ||||
| 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. | |
| reasonGroupIdList | array | Displays as an array of reason group IDs that belong to the reason groups the specified staff is set to offer reasons from. | ||
| reasonIdList | array | Displays as an array of reason IDs that belong to the reasons the specified staff is set to offer. | ||
| salesforceParm1 | ||||
| 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. | |
| securityRole | object | Yes | Provides the security role object for the specified staff. | |
| 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. |
| securityRoles | string | Yes | Displays as the name given to any security roles the specified staff is assigned to. | |
| 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%. | |
| staffRateLevel | string | Displays the staff rating given to the specified staff. | ||
| status | string | Displays as the status of the specified staff. Possible values include "ACTIVE" and "INACTIVE". | ||
| 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. |
| virtualRoomId | integer | Provides a unique numerical ID of the virtual meeting room that's saved on the specified staff's profile. | ||
| virtualRoomUrl | string | Provides the URL of the virtual meeting room that's saved on the specified staff's profile. |