Knowledge Base

Webhooks & APIs

Use Cases

How to use the STAFF API

The following article provides an overview of the Staff API and explains how to use each of its endpoints.

Please take note that this API requires a partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.

Be reminded that the URL at which you access the API depends on your hosting region. This article may present examples from a North American hosting only.

North America	Europe
api.booxi.com	api.booxi.eu

CRUD Endpoints

GET /staff/{staffId}
GET /staff/list
POST /staff/{merchantId}
PUT /staff{staffId}
PUT /staff/{staffId}/userAccess
DELETE /staff/{staffId}
GET /staff/{staffId}/userAccess
GET /staff/{staffId}/passwordRecovery/{requestId}
POST /staff/{staffId}/passwordRecovery

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 merchant 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. Please be aware that 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. Take 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 merchant 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 merchant.

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 merchant 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 merchant. 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.
communciationEmail	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 merchant associated with the Partner API key used.
The associated merchant 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 merchant, 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 merchant that is associated with the Partner API key provided.
The merchant 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 merchant.
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 lwill 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 merchant associated with the Partner API key used.
The associated merchant 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
getStaffPasswordRecovery	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 merchant associated with the Partner API key used.
The associated merchant 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.

For North America	For Europe
createStaffPasswordRecovery	createStaffPasswordRecovery

Limitations & Notes

This API shall not be used to generate reports or export data.
Additional query parameters will be added in future releases.

References

For more information about the Booxi APIs and their usage, please refer to the following links:

Europe: https://api.booxi.eu/doc/booking.html

Americas: https://api.booxi.com/doc/booking.html

API Fair Use & Limitations

Where to find API keys:

Your Merchant API key can be found in the back office, section My Business / Details.
Your Partner API key must be requested to your Booxi Account Manager. The Partner API key must only be used in server-side (backend) code to keep it a secret.

How to use the STAFF API

The following article provides an overview of the Staff API and explains how to use each of its endpoints.

CRUD Endpoints

GET /staff/{staffId}

GET /staff/list

Searching with an externaIId and moduleId

Searching with Contact Info

Successful JSON Response

POST /staff/{merchantId}

Parameters

PUT /staff/{staffId}

PUT /staff/{staffId}/userAccess

DELETE​/staff​/{staffId}

​GET /staff​/{staffId}​/userAccess

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

POST /staff​/{staffId}​/passwordRecovery

Limitations & Notes

References

DELETE/staff/{staffId}

GET /staff/{staffId}/userAccess

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

POST /staff/{staffId}/passwordRecovery