# 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.

With the Staff Members API, you can:

- Manage staff members.
- Manage staff schedules.
- Connect and disconnect Wix users to staff members.

## Before you begin

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

- [Wix Bookings](fallback::https://www.wix.com/app-market/web-solution/bookings)
  must be installed on a site before you can use the Staff Members API.
- Wix Bookings automatically manages a special *resource type*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/resource-types/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resource-types-v2/introduction))
  for all staff members. To avoid data conflicts, don't use the
  *Resources*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/resources/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction))
  and *Resource Types*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/resource-types/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resource-types-v2/introduction))
  APIs to manage staff.
- By default, staff members work during the opening hours of the business's
  *default location*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/business-tools/locations/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/locations/introduction)).
  You can define custom hours by calling
  *Assign Working Hours Schedule to Staff Member*
  ([SDK](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/assign-working-hours-schedule) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/assign-working-hours-schedule)).
  See *how Wix Bookings uses the Calendar APIs*
  ([SDK](fallback::https://dev.wix.com/docs/rest/business-management/calendar/wix-bookings-integration) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/calendar/wix-bookings-integration))
  and the *assign a staff working hour schedule sample flow*
  ([SDK](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/sample-flows#assign-a-staff-working-hour-schedule) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/sample-flows#assign-a-staff-working-hour-schedule))
  for more details.  

## Use Cases

- Connect a staff member to a Wix user
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/sample-flows#backend-modules_bookings_staff-members_connect-a-staff-member-to-a-wix-user) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/sample-flows#connect-a-staff-member-to-a-wix-user)).
- Assign a staff working hour schedule
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/sample-flows#backend-modules_bookings_staff-members_assign-a-staff-working-hour-schedule) | [REST](fallback::http://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/sample-flows#assign-a-staff-working-hour-schedule)).

## Terminology

- __Staff member__: An individual providing services within Wix Bookings.
- __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*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/schedules/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/introduction))
  defining when a staff member is available for bookings. Learn more about
  *how Wix Bookings uses the Calendar APIs*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/wix-bookings-integration) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/calendar/wix-bookings-integration)).
- __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*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-identities) | [REST](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::6a1be8b6-a51a-438e-8ce7-5beb80a5929a*fallback::https://dev.wix.com/docs/rest/articles/getting-started/about-identities)).

For a comprehensive glossary of Wix Bookings terms, see *Terminology*
([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/terminology) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/terminology)).

## See also

- Related APIs:
  - *Services*
  ([SDK](portalId::b85dea5b-341b-493b-b99e-4d4ca12baaa2resourceId::d1c98af6-5ad1-4df4-a38f-0b67797af4d4slug::setup*fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/services/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/services/services-v2/introduction)).
  - *Calendar APIs*
    ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/calendar/introduction)).
  - *Resources*
    ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/resources/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction)).
  - *Resource Types*
    ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/resource-types/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resource-types-v2/introduction)).
  - *Locations API*
    ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/business-tools/locations/introduction) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/locations/introduction)).
- How business owners can:
  - [Manage their resources](fallback::https://support.wix.com/en/article/wix-bookings-managing-your-resources).
  - [Manage their staff](fallback::https://support.wix.com/en/managing-your-staff).

@package_metadata:@wix/bookings

To use the StaffMembers API, install the `@wix/bookings` package.

#### Install the package

Follow the installation instructions for your development environment.

| Development environment | Installation method |
|--|--|
| Wix sites (editor or IDE) | Use the [package manager](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor). |
| Wix sites (local IDE) | Run `wix install @wix/bookings` using the [Wix CLI](fallback::https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli).|
| Blocks apps | Use the same installation method as Wix sites. |
| CLI and self-hosted apps | Run `npm install @wix/bookings` or `yarn add @wix/bookings`. |
| Headless sites and apps | Run `npm install @wix/bookings` or `yarn add @wix/bookings`. |

#### Import the package

To import the package in your code:

```js
import { staffMembers } from '@wix/bookings'
```

# Staff Members API: Sample Use Cases and Flows

This article presents possible use cases that you could support, along with
sample flows to implement each use case. These examples can serve as a helpful
starting point as you plan your implementation.

## Connect a staff member to a Wix user

By connecting a staff member to a Wix user, you enable them to manage their own
working hour schedule in their dashboard.

To connect a staff member to a Wix user:

1. Call *Query Staff Members*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/query-staff-members) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/query-staff-members)).
   Save the relevant staff member ID.
1. Call *Connect Staff Member to User*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/connect-staff-member-to-user) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/connect-staff-member-to-user)).
   Specify the staff member ID. If an existing Wix user is related to the staff
   member but has a different email address than the staff member's `email`,
   specify that email address.
1. Call *Get Staff Member*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/get-staff-member) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/get-staff-member)),
   specifying `ASSOCIATED_IDENTITY_STATUS` in the `fields` parameter.
   Check the value of the `associatedWixIdentity.connection.status` field.

## Assign a staff working hour schedule

By assigning a custom working hour schedule to a staff member, they can have
different working hours than the business.

To assign a working hour schedule to a staff member:

1. Call *Query Staff Members*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/query-staff-members) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/query-staff-members)),
   specifying `RESOURCE_DETAILS` in the `fields` parameter.
   Save the relevant staff member ID and their `resource.eventsSchedule.id`.
1. Call *Assign Working Hours Schedule to Staff Member*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/assign-working-hours-schedule) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/assign-working-hours-schedule)).
   Specify the values retrieved in the previous step as `staffMemberId` and
   `scheduleId`. Note that you must specify the *event schedule* ID from step 1,
   even though the method is called
   *Assign Working Hours Schedule to Staff Member*.
1. Optional: If you want to add working hours, call *Create Event*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/create-event) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/calendar/events-v3/create-event)).
   Specify the schedule ID. If it's a recurring event, specify also
   `recurrenceRule`. Learn more about *recurring events*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/recurring-events) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/calendar/events-v3/recurring-events)).
1. Optional: If you want to remove working hours, call *Cancel Event*
   ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/calendar/events/cancel-event) | [REST](fallback::https://dev.wix.com/docs/rest/business-management/calendar/events-v3/cancel-event)).

# Staff Members: Filtering and Sorting

This article covers field support for filtering in:

- *Query Staff Members*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/query-staff-members) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/query-staff-members)).
- *Search Staff Members*
  ([REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/search-staff-members)).
- *Count Staff Members*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/count-staff-members) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/count-staff-members)).
- *Bulk Update Staff Member Tags By Filter*
([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/bulk-update-staff-member-tags-by-filter) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/bulk-update-staff-member-tags-by-filter)).

## Filtering

Specify the `filter` object in the following format:

```json
{
  "filter": {
    "fieldName": {
      "$eq": "value"
    }
  }
}
```

The following table shows field support for filters and sorting for the
`staffMember` object:

| Field                                                                           | Supported Filters                                     | Sortable |
|---------------------------------------------------------------------------------|-------------------------------------------------------|----------|
| `id`                                                                            | `$eq`, `$ne`, `$exists`, `$in`, `$nin`, `$startsWith` | Sortable |
| `description`                                                                   | `$eq`, `$ne`, `$exists`, `$in`, `$nin`, `$startsWith` | Sortable |
| `name`                                                                          | `$eq`, `$ne`, `$exists`, `$in`, `$nin`                |          |
| `email`                                                                         | `$eq`, `$ne`, `$exists`, `$in`, `$nin`                |          |
| `phone`                                                                         | `$eq`, `$ne`, `$exists`, `$in`, `$nin`                |          |
| `default`                                                                       | `$eq`, `$ne`, `$exists`, `$in`, `$nin`                |          |
| `associatedWixIdentity.identificationData.contactId`                            | `$eq`, `$ne`, `$exists`, `$in`, `$nin`, `$startsWith` | Sortable |
| `associatedWixIdentity.identificationData.wixUserId`                            | `$eq`, `$ne`, `$exists`, `$in`, `$nin`, `$startsWith` | Sortable |
| `associatedWixIdentity.identificationData.identityType`                         | `$eq`, `$ne`, `$exists`, `$in`, `$nin`, `$startsWith` | Sortable |
| `resource.locationOptions.specificLocationOptions.businessLocations.locationId` | `$hasSome`, `$hasAll`, `$isEmpty`                     |          |

## Sorting

Results in *Query Staff Members*
([SDK](fallback::https://dev.wix.com/docs/sdk/backend-modules/bookings/staff-members/query-staff-members) | [REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/query-staff-members)),
and *Search Staff Members*
([REST](fallback::https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/search-staff-members))
are sorted by the `id` field in ascending order by default.

To sort by a different field, use the `sort` object in the following format:

```json
{
  "sort": [
    {
      "fieldName": "description",
      "order": "DESC"
    }
  ]
}
```

## See also

- *API Query Language*
  ([SDK](fallback::https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/api-query-language) | [REST](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::8158a590-f60c-4606-9fed-16a34e275f3a*fallback::https://dev.wix.com/docs/rest/articles/getting-started/api-query-language)).

createStaffMember( )