How to use the STAFF API | Booxi Help Center

Use of this API requires a partner API Key. To obtain such a key, contact your Booxi representative.
Prior to use, consult Booxi's API fair use policy.
Remember that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting only.
API documentation links:
- North America
- Europe

GET /staff/{staffId}

Retrieve the staff record associated with the provided staffId.

Permissions and Security

This endpoint requires a valid Partner API Key.

Parameters

Parameter	Format	Description
staffId	integer	ID of the staff to look for. This parameter is mandatory.

Request URL for North America

https://api.booxi.com/booking/v1/staff/{staffId}

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/{staffId}

cURL

curl -X GET "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID"
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

Successful Response

Here's an example of a successful response

{
  "id": 11111,
  "name": "Mike Wright",
  "firstName": "Mike",
  "lastName": "Wright",
  "position": "Owner",
  "biography": "",
  "profileImageUrl": "image_url",
  "timeSelectionMode": "ServiceTimeSelection",
  "mobilePhone": "+1234555666",
  "workPhone": "+1234555666",
  "communicationEmail": "mail@domain.com",
  "loginEmail": "mail@domain.com",
  "userRole": "Admin",
  "invitationStatus": "Accepted",
  "language": "eng",
  "personnelType": "Standard",
  "status": "Online",
  "createdOn": "2020-06-15T15:36:20Z",
  "modifiedOn": "2024-02-20T06:51:07Z"
}

You can test this endpoint at the following links.

For North America	For Europe
getStaff	getStaff

GET /staff/list

Retrieve a list of all staff of a given partnership. Queries can be performed with different search criteria. See below for examples.

Use Cases

Here are a few use cases where the GET/staff/list API endpoint is used in practical applications.

Custom Clienteling Application

Retrieve the list of staff to find a calendar to book an appointment, list staff available calendars, or select a staff offering a given service.

HR System (using external module)

Retrieve the list of staff to find a specific employee using the external module, with its associated external staff id.

Permissions and Security

This endpoint requires a valid Partner API Key.
When querying, the moduleId must belong to an active store that is associated with the Partner API Key provided.

Parameters

Parameter	Format	Description
externalId	string	The external id associated with a staff in the module as defined by moduleId. This field is mandatory when searching with a module ID.
moduleId	string	The ID of the module to search in. This field is mandatory when searching with an external ID.
merchantId	integer	The merchant id to which the staff are accessible. This field is mandatory for any query made without providing an externalId and moduleId.
firstName	string	The first name of the staff to look for. This field is mandatory when lastName is provided.
lastName	string	The last name of the staff. This field is mandatory when lastName is provided.
communicationEmail	string	The email used to communicate with the staff. This field is optional.
loginEmail	string	The email used by the staff to log into Booxi. This field is optional.
status	string	The status of the staff, Online or Offline. This field is optional and is used to filter the results.
personnelType	string	The staff personnel type, User or Standard. This field is optional and is used to filter the result.

Limitations

The moduleId must be valid.
The moduleId provided must be associated with the Partner API key provided.
The resulting list of staff will exclude any staff that were deleted.

Request URL for North America

https://api.booxi.com/booking/v1/staff/list

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/list

Searching with an externaIId and moduleId

Get a list of all staff associated with the externalId and moduleId provided with the query; both parameters are mandatory.

Limitations

The moduleId must be valid.
The moduleId provided must be associated with the Partner API key provided.
The resulting list of staff will exclude any staff that were deleted.

cURL for North America

curl -X GET "https://api.booxi.com/booking/v1/staff/list?externalId=EXTERNAL_ID&moduleId=MODULE_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

cURL for Europe

curl -X GET "https://api.booxi.eu/booking/v1/staff/list?externalId=EXTERNAL_ID&moduleId=MODULE_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

Searching with Contact Info

Get a list of staff that match the firstName and lastName, communicationEmail or loginEmail provided with the query. Note that if an externalId and moduleId are not provided with the query, the parameter merchantId will be mandatory.

Limitations

The moduleId must be valid.
The moduleId provided must be associated with the Partner API key provided.
If provided, the merchantId must be valid and not disabled.
The moduleId provided must be associated with the Partner API key provided.
The firstName and lastName parameters must be provided together and must be an exact match to the values contained in the staff profile.
The resulting list of staff will exclude any staff that were deleted.

cURL for North America

curl -X GET "https://api.booxi.com/booking/v1/staff/list?merchantId=YOUR_MERCHANT_ID&firstName=STAFF_FIRST_NAME&lastName=STAFF_LAST_NAME&communicationEmail=COMMUNICATION_EMAIL&loginEmail=LOGIN_EMAIL" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

cURL for Europe

curl -X GET "https://api.booxi.eu/booking/v1/staff/list?merchantId=YOUR_MERCHANT_ID&firstName=STAFF_FIRST_NAME&lastName=STAFF_LAST_NAME&communicationEmail=COMMUNICATION_EMAIL&loginEmail=LOGIN_EMAIL" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

Successful JSON Response

When the query is successful, the response will include a list of all staff that match the search criteria.

Here’s an example of a successful response:

{
  "staffs": [
    {
      "id": 1,
      "name": "John Smith",
      "firstName": "John",
      "lastName": "Smith",
      "position": "Manager",
      "biography": "",
      "profileImageUrl": "https://www.booxi.com/images/profile.png",
      "timeSelectionMode": "ServiceTimeSelection",
      "mobilePhone": "+15552346789",
      "workPhone": "+15552346789",
      "communicationEmail": "user@domain.com",
      "loginEmail": "user@domain.com",
      "userRole": "Admin",
      "invitationStatus": "Accepted",
      "language": "eng",
      "personnelType": "User",
      "status": "Online"
    },
    {
      "id": 2,
      "name": "Mike Brown",
      "firstName": "Mike",
      "lastName": "Brown",
      "position": "Staff",
      "biography": "",
      "profileImageUrl": "https://www.booxi.com/images/profile.png",
      "timeSelectionMode": "ServiceTimeSelection",
      "mobilePhone": "+15552346789",
      "workPhone": "+15552346789",
      "communicationEmail": "user@domain.com",
      "loginEmail": "user@domain.com",
      "userRole": "Admin",
      "invitationStatus": "Accepted",
      "language": "eng",
      "personnelType": "User",
      "status": "Online"
    }
  ]
}

You can test this API at the following links.

For North America	For Europe
getStaffList	getStaffList

POST /staff/{merchantId}

Create a new staff record using the information provided in the request body and assign this new staff to the store associated with the provided merchantId. The parameter merchantId is mandatory. Options include:

Option 1: Create a new staff profile (default case)
Option 2: Create a staff by duplicating an existing staff profile, using the queryParam 'fromStaffId'; doing so duplicates all personnel details (unless specified otherwise in the request body) as well as the booking rules, the assigned services, the staff translations and the profile picture.
Option 3: Create a staff using an existing personnel template, using the queryParam 'fromStaffIdTemplateId'. The created staff will inherit all data included in the template: all personnel details (unless specified otherwise in the request body) except for first and last name, all assigned services, booking rules, the staff translations and the profile picture. See here for more information on staff templates.

Permissions and Security

A valid Partner API key is required.
The merchant ID provided must be associated with the Partner API key provided.

*Requirements:

The merchantId provided must be valid.
The merchantId provided must be associated with an active store.

Option 2: Duplicate an existing staff record

*Requirements:

The origin staff must exist (i.e. is not deleted).
The origin staff must belong to the merchantId in which the new staff will be created.

*Notes:

Any custom edits made to price and/or service associated with the origin staff will not be copied over to the new staff.
The origin staff’s user access [if applicable] will not be copied over to the new staff.

Option 3: Create from staff template

*Requirements:

The staff template must exist (i.e. is not deleted).
The template must belong to the Head Office associated with the merchant ID provided.

Parameters

Field	Format	Description
merchantId	integer	Id of the store the staff is created for. This parameter is mandatory.
fromStaffId	integer	Id of the staff to duplicate; the staff must belong to the same merchant. This parameter is optional.
fromStaffTemplateId	integer	The id of the staff template to use to create the staff. The template must belong to the Head Office of the store. Optional.

Example of a request body

{
  "firstName": "John",
  "lastName": "Smith",
  "position": "manager",
  "biography": " ",
  "workPhone": "+15552346789",
  "communicationEmail": "john.smith@domain.com",
  "mobilePhone": "+15552346789",
  "personnelType": "standard",
  "language": "eng",
  "status": "Offline",
  "timeSelectionMode": "ClientTimes"
}

Request URL for North America

https://api.booxi.com/booking/v1/staff/{merchantId}

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/{merchantId}

cURL
Here’s an example using the body request provided above.

curl -X POST  "https://api.booxi.com/booking/v1/staff/YOUR_MERCHANT_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-H  "Content-Type: application/json" -d "{\"firstName\":\"John\",\"lastName\":\"Smith\",\"position\":\"manager\",\"biography\":\"\",\"workPhone\":\"+15552346789\",\"communicationEmail\":\"john.smith@domain.com\",\"mobilePhone\":\"+15552346789\",\"personnelType\":\"standard\",\"language\":\"eng\",\"status\":\"Offline\",\"timeSelectionMode\":\"ClientTimes\"}"

Successful Response
Here’s an example of a newly created staff record.

{
  "id": 69285,
  "name": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "position": "manager",
  "biography": "",
  "profileImageUrl": "",
  "timeSelectionMode": "ClientTimes",
  "mobilePhone": "+818093442001",
  "workPhone": "+818093442001",
  "communicationEmail": "john.smith@domain.com",
  "loginEmail": "",
  "userRole": "Staff",
  "invitationStatus": "ToInvite",
  "language": "eng",
  "personnelType": "Standard",
  "status": "Offline",
  "createdOn": "2024-04-04T08:16:26Z",
  "modifiedOn": "2024-04-04T08:16:26Z"
  "isTemplate": false
}

You can test this endpoint at the following links.

For North America	For Europe
createStaff	createStaff

PUT /staff/{staffId}

Update an existing staff record using the information provided in the request body.

Parameters

Field	Format	Description
staffId	integer	Id of the staff to update. This parameter is mandatory.

Request Body

Field	Format	Description
firstName	string	Staff's first name.
lastName	string	Staff's last name.
position	string	Role assigned to the staff.
biography	string	Staff's biography.
workPhone	string	Staff's phone number at work.
communicationEmail	string	Staff's email address.
mobilePhone	string	Staff's mobile phone number.
language	string	Staff's preferred language.
status	string	Staff's status, online or offline.
timeSelectionMode	string	Time selection mode assigned to the staff.

*Note

The staff id must belong to a store associated with the Partner API key used.
The associated store must not be disabled.
Accessible if the Partner API Key is authorized for this endpoint.

Example of a request body

{
  "firstName": "John",
  "lastName": "Smith",
  "position": "manager",
  "biography": "",
  "workPhone": "+12345556666",
  "communicationEmail": "mail@domain.com",
  "mobilePhone": "+12345556666",
  "language": "eng",
  "status": "Offline",
  "timeSelectionMode": "ClientTimes"
}

Request URL for North America

https://api.booxi.com/booking/v1/staff/{staffId}

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/{staffId}

Successful Response

The updated staff record.

{
  "id": 1,
  "name": "John Smith",
  "firstName": "John",
  "lastName": "Smith",
  "position": "manager",
  "biography": "",
  "profileImageUrl": "",
  "timeSelectionMode": "ClientTimes",
  "mobilePhone": "+12345556666",
  "workPhone": "+12345556666",
  "communicationEmail": "mail@domain.com",
  "loginEmail": "",
  "userRole": "Staff",
  "invitationStatus": "ToInvite",
  "language": "eng",
  "personnelType": "Standard",
  "status": "Offline",
  "createdOn": "2024-04-04T08:16:26Z",
  "modifiedOn": "2024-04-11T09:51:52Z"
}

You can test this endpoint at the following links.

For North America	For Europe
updateStaff	updateStaff

PUT /staff/{staffId}/userAccess

Add or update a new user access to a staff.

Permissions and Security

The merchant ID provided must be associated with the Partner API key provided.
The partner API key must have access to the target staffId.

*Requirements:

The merchantId provided must be valid.
The merchantId associated with the target staff must be active.
The target staff must exist (i.e. is not deleted).
The loginEmail cannot be null.
If there is an IDP set for the store, the target staff login email domain must match the domain set for the IDP.

Parameters

Field	Format	Description
staffId	integer	Target staff Id. This parameter is mandatory.
sendEmailInvite	boolean	Determines if an invitation email to join Booxi will be sent to the staff when creating its user access. Defaults to true.

Example of a request body

{
 "staffId": 1234,
 "userRole": "Staff",
 "canLogin": true,
 "loginEmail": "gloria@gmail.com"
}

Request URL for North America

https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/userAccess?sendEmailInvite=true

Request URL for Europe

https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/userAccess?sendEmailInvite=true

cURL

curl -X PUT "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/userAccess?sendEmailInvite=true" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-H  "Content-Type: application/json" -d "{\"staffId\":1234,\"userRole\":\"Staff\",\"canLogin\":true,\"loginEmail\":\"gloria@gmail.com\"}"

Successful Response

The updated staff record.

{
  "userAccess": {
  "staffId": 1234,
  "loginEmail": "gloria@gmail.com",
    "userRole": "Staff",
    "provider": "booxi",
    "providerName": "",
    "canLogin": true
  },
  "staff": {
  "id": 1234,
    "name": "Gloria Truant",
    "firstName": "Gloria",
    "lastName": "Truant",
    "position": "",
    "biography": "I'm 25, I like to dance and sing in my free time.",
  "profileImageUrl": "",
    "timeSelectionMode": "ClientTimes",
    "mobilePhone": "",
    "workPhone": "",
  "communicationEmail": "gloria@gmail.com",
  "loginEmail": "gloria@gmail.com",
    "userRole": "Staff",
    "invitationStatus": "Invited",
    "language": "eng",
    "personnelType": "Standard",
    "status": "Online",
    "createdOn": "2024-05-10T21:16:24Z",
    "modifiedOn": "2024-06-07T14:23:40Z"
  }
}

You can test this endpoint at the following links.

For North America	For Europe
saveUserAccess	saveUserAccess

DELETE/staff/{staffId}

Delete an existing staff record.

Parameters

Field	Format	Description
staffId	integer	ID of the staff to delete. This parameter is mandatory.

*Note

The staff ID provided must belong to a store that is associated with the Partner API key provided.
The store that the staff ID is associated with must be active (i.e. not disabled).

Request URL for North America

https://api.booxi.com/booking/v1/staff/{staffId}

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/{staffId}

cURL

Here’s an example of a valid query.

curl -X DELETE "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

Successful Response

The deleted staff record.

{
 "id": 1,
 "name": "John Smith",
 "firstName": "John",
 "lastName": "Smith",
 "position": "manager",
 "biography": "",
 "profileImageUrl": "",
 "timeSelectionMode": "ClientTimes",
 "mobilePhone": "+12345556666",
 "workPhone": "+12345556666",
 "communicationEmail": "mail@domain.com",
 "loginEmail": "",
 "userRole": "Staff",
 "invitationStatus": "ToInvite",
 "language": "eng",
 "personnelType": "Standard",
 "status": "Offline",
 "createdOn": "2024-04-04T08:16:26Z",
 "modifiedOn": "2024-04-11T10:17:23Z"
}

You can test this endpoint at the following links.

For North America	For Europe
deleteStaff	deleteStaff

GET /staff/{staffId}/userAccess

Retrieve the user access of a given staff.

Limitations

Staff must belong to an active store.
Staff must not be deleted.

Notes

In the “userAccess” portion of the request body:
- If user access is found for the staffId provided: "provider" and "canlogin" fields will be shown (otherwise, these fields will not be shown)
- If no user access is found for the staffId provided: the “loginEmail” field will be empty.
The “providerName” field will be populated only if there is a user access associated and the associated provider is not “booxi” (otherwise, it will be blank)

Parameters

Field	Format	Description
staffId	integer	Target staff ID. This parameter is mandatory.

Successful Response

Here’s an example of a successful response.

{
"userAccess": {
  "staffId": 3712,
  "loginEmail": "emilie.authier@booxi.com",
  "userRole": "Admin",
  "provider": "booxi",
  "providerName": "Google",
  "canLogin": true,
  "lastLogin": "2022-05-20T07:15:00Z"
},
"staff": {
  "id": 1,
  "name": "Jane Poe",
  "firstName": "Jane",
  "lastName": "Poe",
  "position": "Manager",
  "biography": "The friendly manager.",
  "profileImageUrl": "https://www.booxi.com/images/1tg3XisyCv0J9fQX.png",
  "timeSelectionMode": "ServiceTimeSelection",
  "mobilePhone": "+15552346789",
  "workPhone": "+15552346789",
  "communicationEmail": "emilie.authier@booxi.com",
  "loginEmail": "emilie.authier@booxi.com",
  "userRole": "Admin",
  "invitationStatus": "Accepted",
  "language": "eng",
  "personnelType": "User",
  "status": "Online",
  "createdOn": "2020-01-01T07:15:00Z",
  "modifiedOn": "2020-01-01T07:30:00Z"
}
}

Request URL for North America

https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/userAccess

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/YOUR_STAFF_ID/userAccess

cURL

curl -X GET "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/userAccess" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

You can test this endpoint at the following links.

For North America	For Europe
getUserAccess	getUserAccess

GET /staff/{staffId}/passwordRecovery/{requestId}

Retrieve the information related to a given staff’s password reset request.

Parameters

Field	Format	Description
staffId	integer	Id of the target staff; mandatory.
requestId	integer	The id of the password recovery request; mandatory.

*Requirements:

Staff Id must belong to a store associated with the Partner API key used.
The associated store must not be disabled.
Staff must not be deleted.
The password recovery requestId must be associated with the staffId provided.

Request URL for the North America

https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/passwordRecovery/REQUEST_ID

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/YOUR_STAFF_ID/passwordRecovery/REQUEST_ID

cURL

curl -X GET "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/passwordRecovery/REQUEST_ID" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

Successful Response

Here’s an example of a successful response.

{
"requestId": 1,
"staffId": 3712,
"loginEmail": "emilie.authier@booxi.com",
"code": 10608034,
"staffFirstName": "Jane",
"staffLastName": "Poe",
"requestDate": "2012-05-20T07:15:00Z",
"codeState": "Valid"
}

You can test this endpoint at the following links.

For North America

For Europe

Europe is a continent located entirely in the Northern Hemisphere and mostly in the Eastern Hemisphere. It is bordered by the Arctic Ocean to the north, the Atlantic Ocean to the west, and the Mediterranean Sea to the south. Europe is the second-smallest continent by surface area, covering about 10.2 million square kilometers or 6.8% of the Earth's land area. It is also the third-most populous continent, with a population of over 740 million people.

Europe is known for its rich history, diverse cultures, and stunning landscapes. It is home to some of the world's most iconic landmarks such as the Eiffel Tower in Paris, the Colosseum in Rome, and the Acropolis in Athens. It is also the birthplace of Western civilization and has played a significant role in shaping the modern world.

With 44 countries, Europe offers a wide range of experiences for travelers. From the bustling cities of London and Berlin to the picturesque villages of the Swiss Alps and the Mediterranean coast, there is something for everyone in Europe. It is also a popular destination for food lovers, with each country having its own unique cuisine and specialties.

If you are planning a trip to Europe, it is important to research the visa requirements for your specific country of origin. Some countries may require a visa, while others may allow for visa-free travel. It is also recommended to have a valid passport with at least six months of validity remaining.

In terms of transportation, Europe has a well-developed network of trains, buses, and flights, making it easy to travel between countries. It is also a popular destination for road trips, with many scenic routes and picturesque towns to explore.

When it comes to currency, most countries in Europe use the Euro, but there are a few exceptions such as the United Kingdom, Switzerland, and Norway. It is always a good idea to have some local currency on hand for smaller purchases and to avoid any currency exchange fees.

In conclusion, Europe is a diverse and fascinating continent with something for every type of traveler. Whether you are interested in history, culture, food, or nature, Europe has it all. So start planning your trip and get ready to explore this beautiful continent!

getStaffPasswordRecovery

POST /staff/{staffId}/passwordRecovery

Generate a code that can be used to reset the password of a given staff’s user account.

Parameters

Field	Format	Description
staffId	integer	Id of the target staff; mandatory.

*Requirements:

Staff Id must belong to a store associated with the Partner API key used.
The associated store must not be disabled.
Staff must not be deleted.
The staff must have a user account.

*Notes:

A maximum of five reset attempts (including reset attempts made by the user in the Back Office) are permitted per user. Once the five attempts have been made, an error will be returned.

Request URL for the North America

https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/passwordRecovery

Request URL for Europe

https://api.booxi.eu/booking/v1/staff/YOUR_STAFF_ID/passwordRecovery

cURL

curl -X POST "https://api.booxi.com/booking/v1/staff/YOUR_STAFF_ID/passwordRecovery" 
-H  "accept: application/json" 
-H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
-d ""

Successful Response

Here’s an example of a successful response.

{
  "requestId": 1,
  "staffId": 3712,
  "loginEmail": "emilie.authier@booxi.com",
  "code": 10608034,
  "staffFirstName": "Jane",
  "staffLastName": "Poe",
  "requestDate": "2012-05-20T07:15:00Z",
  "codeState": "Valid"
}

You can test this endpoint at the following links.