About the Staff Members API

The Staff Members API enables you to manage the staff of a business and their working hour schedules. If a staff member is a Wix user, they can manage their own schedule through the dashboard.

A business's staff isn't limited to the people who deliver services to customers. Receptionists, managers, and cashiers are staff members too. They have working hours and appear in the staff list, but customers can't book them. The serviceProvider field marks which staff members are bookable.

With the Staff Members API, you can:

• Manage staff members.
• Manage staff schedules.
• Retrieve the business's service providers, or its entire staff.
• Promote and demote staff members between service providers and non-providers.
• Connect and disconnect Wix users to staff members.

Service providers

serviceProvider drives both which staff appear in booking flows and which staff the read methods return by default.

Set it when you create a staff member, with the serviceProvider field of Create Staff Member. Change it afterward by calling Set Service Provider. Promoting a staff member also grants the Wix user connected to them the Staff role, if they don't already have it. Demoting doesn't revoke that role, and doesn't remove the staff member's working hours, service assignments, or existing bookings. They just stop appearing in booking flows, and the call is reversible.

The API provides 2 sets of read methods, which differ in the staff they return by default:

• Query Staff Members, Search Staff Members, and Count Staff Members return only service providers, unless you pass an explicit serviceProvider filter. Use them for booking flows, such as letting a customer choose who delivers a service.
• Query Staff Members V2, Search Staff Members V2, and Count Staff Members V2 return the entire staff, including staff members who don't provide services. Use them for team management flows, such as a staff directory or a working hours planner. To narrow the results to service providers only, filter by serviceProvider.

Before you begin

It’s important to note the following points before starting to code:

• Wix Bookings must be installed on a site before you can use the Staff Members API.
• Wix Bookings automatically manages a special resource type for all staff members. To avoid data conflicts, don't use the Resources V2 and Resource Types V2 APIs to manage staff.
• By default, staff members work during the opening hours of the business's default location. You can define custom hours by calling Assign Working Hours Schedule to Staff Member and then creating WORKING_HOURS events with the Calendar Events V3 API. See how Wix Bookings uses the Calendar APIs and the set a staff member's weekly working hours sample flow for more details.
• To block a staff member's availability for vacation days or time off, create an OPAQUE event on their event schedule using the Calendar Events V3 API. See the block a staff member's availability for a vacation day sample flow.
• To get a staff member's event schedule ID, call Get Staff Member with RESOURCE_DETAILS in the fields parameter and read the resource.eventsSchedule.id field.
• name, email, and phone hold personally identifiable information. You can sort on them in the Search methods, but the Query methods reject a sort on any of them with an INVALID_SORT error. For the fields you can filter and sort by, see Filtering and Sorting.

Use cases

• Connect a staff member to a Wix user.
• Build a staff directory of the entire team.
• Make a staff member bookable.
• Set a staff member's weekly working hours.
• Block a staff member's availability for a vacation day.

Terminology

• Staff member: An individual who works for the business. Some staff members deliver services to customers, and others, such as receptionists and managers, don't.
• Service provider: A staff member who delivers services to customers and who customers can book. Indicated by the serviceProvider field.
• Resource: An asset, such as a meeting room or equipment, needed to deliver services to customers.
• Resource type: A classification that connects resources, making them bookable.
• Working hour schedule: A schedule defining when a staff member is available for bookings. Learn more about how Wix Bookings uses the Calendar APIs.
• Wix user: An individual logged into their account on .wix.com. This includes site owners, collaborators, and app owners. Not all staff members are Wix users, and not all users connected to a Wix Bookings site are staff members. Learn more about identities.

For a comprehensive glossary of Wix Bookings terms, see Terminology.

See also

• Related APIs:
  • Services
  • Calendar APIs
  • Calendar Events
  • Calendar Schedules
  • Resources
  • Resource Types
  • Locations
• How business owners can:
  • Manage their resources.
  • Manage their staff.