openapi: 3.0.3
info:
title: Phorest Third-Party API
description: >-
The Phorest API exposes a partner-gated business's salon/spa data -
clients, appointments, bookings, staff, services, products, purchases,
vouchers, loyalty, and reporting - for approved integrators. Access is
granted by Phorest support on request (quoting a Phorest Account Number),
not through self-service signup. Requests use HTTP Basic authentication
with a `global/{email}` username and a Phorest-issued API password, and
are scoped in the URL path to a `businessId` and, for most resources, a
`branchId`. Endpoints, methods, and parameters in this document are
transcribed from Phorest's public API reference at
developer.phorest.com/reference; a small number of item-level paths
(marked in their description) are modeled by convention from the
confirmed collection-level siblings because Phorest's public reference
does not expose every single-resource path in plain text.
version: '1.0'
contact:
name: Phorest API Support
email: api-requests@phorest.com
url: https://developer.phorest.com/docs/getting-started
license:
name: Proprietary - partner access only
url: https://developer.phorest.com/docs/requesting-assistance-with-the-phorest-api
servers:
- url: https://api-gateway-eu.phorest.com/third-party-api-server/api/business
description: EU production gateway
- url: https://api-gateway-us.phorest.com/third-party-api-server/api/business
description: US/AUS production gateway
- url: https://platform.phorest.com/third-party-api-server/api/business
description: EU production alias documented in Phorest support articles
security:
- basicAuth: []
tags:
- name: Clients
description: Client (customer) records and client categories.
- name: Appointments
description: Appointment lifecycle - list, retrieve, update, cancel, confirm, check in.
- name: Bookings
description: Booking creation and lifecycle, plus real-time availability checks.
- name: Staff
description: Staff records, rota/work-time tables, and staff breaks.
- name: Services
description: Services, service categories, packages, and special offers.
- name: Branches
description: Branches (locations), rooms, machines, and tax rates.
- name: Products
description: Retail products and inventory.
- name: Purchases
description: Point-of-sale purchases, stock adjustments, and till balances.
- name: Vouchers
description: Gift voucher creation, lookup, and balance updates.
- name: Loyalty
description: Client loyalty point adjustments.
- name: Courses
description: Course templates and a client's purchased course sessions.
- name: Reporting
description: Asynchronous CSV export jobs for sale-level reporting.
- name: Reviews
description: Client reviews for syndication to external review platforms.
- name: Leads
description: Marketing leads and lead statistics.
paths:
/{businessId}/client:
parameters:
- $ref: '#/components/parameters/BusinessId'
get:
operationId: getClients
tags: [Clients]
summary: List clients
description: >-
Lists clients for a business, filterable by email, phone, name, or
update time. Confirmed: developer.phorest.com/reference/getclients.
parameters:
- name: email
in: query
schema: { type: string }
- name: phone
in: query
schema: { type: string }
- name: firstName
in: query
schema: { type: string }
- name: lastName
in: query
schema: { type: string }
- name: externalId
in: query
schema: { type: string }
- name: updatedAfter
in: query
schema: { type: string, format: date-time }
- name: updatedBefore
in: query
schema: { type: string, format: date-time }
- name: includeArchived
in: query
schema: { type: boolean }
- name: includeDeleted
in: query
schema: { type: boolean }
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Clients listed successfully.
content:
application/json:
schema:
type: object
properties:
_embedded:
type: object
properties:
clients:
type: array
items: { $ref: '#/components/schemas/Client' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
'500': { $ref: '#/components/responses/ServerError' }
post:
operationId: createClient
tags: [Clients]
summary: Create a client
description: >-
Creates a client - for example from a website newsletter signup.
Confirmed: developer.phorest.com/docs/using-the-client-endpoint.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ClientInput' }
responses:
'201':
description: Client created successfully.
content:
application/json:
schema: { $ref: '#/components/schemas/Client' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
'500': { $ref: '#/components/responses/ServerError' }
/{businessId}/client/{clientId}:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/ClientId'
get:
operationId: getClient
tags: [Clients]
summary: Retrieve a client
description: >-
Retrieves a single client by ID. Modeled by convention from the
confirmed getClients/updateClient siblings - not shown as its own
text page in the public reference.
responses:
'200':
description: The requested client.
content:
application/json:
schema: { $ref: '#/components/schemas/Client' }
'404': { $ref: '#/components/responses/NotFound' }
put:
operationId: updateClient
tags: [Clients]
summary: Update a client
description: >-
Updates an existing client. The request body must include the
client's current `version`; Phorest increments it on success.
Confirmed: developer.phorest.com/docs/using-the-client-endpoint.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ClientInput' }
responses:
'200':
description: Client updated successfully.
content:
application/json:
schema: { $ref: '#/components/schemas/Client' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
/{businessId}/client/walkin:
parameters:
- $ref: '#/components/parameters/BusinessId'
get:
operationId: getWalkInClient
tags: [Clients]
summary: Retrieve the walk-in client
description: >-
Retrieves the business's placeholder "walk-in" client record, used
for bookings/purchases with no named client. Modeled from the
reference page name getwalkinclient by convention with the client
resource root.
responses:
'200':
description: The walk-in client record.
content:
application/json:
schema: { $ref: '#/components/schemas/Client' }
/{businessId}/category/client:
parameters:
- $ref: '#/components/parameters/BusinessId'
get:
operationId: getClientCategories
tags: [Clients]
summary: List client categories
description: >-
Lists client categories used for marketing/newsletter segmentation.
Confirmed: developer.phorest.com/reference/getclientcategories.
parameters:
- name: name
in: query
schema: { type: string }
- name: includeArchived
in: query
schema: { type: boolean }
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Client categories listed successfully.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/ClientCategory' }
/{businessId}/category/client/{categoryId}:
parameters:
- $ref: '#/components/parameters/BusinessId'
- name: categoryId
in: path
required: true
schema: { type: string }
get:
operationId: getClientCategory
tags: [Clients]
summary: Retrieve a client category
description: >-
Retrieves a single client category by ID. Modeled by convention from
the confirmed getClientCategories sibling.
responses:
'200':
description: The requested client category.
content:
application/json:
schema: { $ref: '#/components/schemas/ClientCategory' }
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/appointment:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
get:
operationId: getAppointments
tags: [Appointments]
summary: List appointments
description: >-
Lists appointments for a business/branch over at most a one-month
range, filterable by date, update time, staff, room, machine, client,
or group booking. Confirmed:
developer.phorest.com/reference/getappointments.
parameters:
- name: from_date
in: query
schema: { type: string, format: date }
- name: to_date
in: query
schema: { type: string, format: date }
- name: staff_id
in: query
schema: { type: string }
- name: room_id
in: query
schema: { type: string }
- name: machine_id
in: query
schema: { type: string }
- name: client_id
in: query
schema: { type: string }
- name: group_booking_id
in: query
schema: { type: string }
- name: fetch_canceled
in: query
schema: { type: boolean }
- name: fetch_deleted
in: query
schema: { type: boolean }
- name: fetch_archived
in: query
schema: { type: boolean }
- name: fetch_notes
in: query
schema: { type: boolean }
- name: updated_from
in: query
schema: { type: string, format: date-time }
- name: updated_to
in: query
schema: { type: string, format: date-time }
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Appointments listed successfully.
content:
application/json:
schema:
type: object
properties:
_embedded:
type: object
properties:
appointments:
type: array
items: { $ref: '#/components/schemas/Appointment' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
'500': { $ref: '#/components/responses/ServerError' }
/{businessId}/branch/{branchId}/appointment/{appointmentId}:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- $ref: '#/components/parameters/AppointmentId'
get:
operationId: getAppointment
tags: [Appointments]
summary: Retrieve an appointment
description: >-
Retrieves a single appointment by ID. Modeled by convention from the
confirmed getAppointments/updateAppointment siblings.
responses:
'200':
description: The requested appointment.
content:
application/json:
schema: { $ref: '#/components/schemas/Appointment' }
'404': { $ref: '#/components/responses/NotFound' }
put:
operationId: updateAppointment
tags: [Appointments]
summary: Update an appointment
description: >-
Updates an appointment (for example rescheduling or reassigning
staff/room). Confirmed to exist:
developer.phorest.com/reference/updateappointment; sub-path modeled
by convention with the confirmed collection path.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/AppointmentInput' }
responses:
'200':
description: Appointment updated successfully.
content:
application/json:
schema: { $ref: '#/components/schemas/Appointment' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
/{businessId}/branch/{branchId}/appointment/{appointmentId}/cancel:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- $ref: '#/components/parameters/AppointmentId'
post:
operationId: cancelAppointment
tags: [Appointments]
summary: Cancel an appointment
description: >-
Cancels an appointment. Confirmed to exist:
developer.phorest.com/reference/cancelappointments; sub-path modeled
by convention with the confirmed action-suffix pattern used by
cancelBooking/confirmAppointment.
responses:
'200':
description: Appointment canceled successfully.
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/appointment/{appointmentId}/confirm:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- $ref: '#/components/parameters/AppointmentId'
post:
operationId: confirmAppointment
tags: [Appointments]
summary: Confirm an appointment
description: >-
Marks an appointment as confirmed. Confirmed to exist:
developer.phorest.com/reference/confirmappointments; sub-path
modeled by convention.
responses:
'200':
description: Appointment confirmed successfully.
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/appointment/{appointmentId}/checkin:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- $ref: '#/components/parameters/AppointmentId'
post:
operationId: checkInAppointment
tags: [Appointments]
summary: Check in an appointment
description: >-
Checks a client in for an appointment. Confirmed to exist:
developer.phorest.com/reference/checkin_1; sub-path modeled by
convention.
responses:
'200':
description: Appointment checked in successfully.
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/appointments/availability:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
post:
operationId: checkAppointmentAvailability
tags: [Bookings]
summary: Check appointment availability
description: >-
Returns available appointment slots for a set of requested services
within a time window; optionally scoped to a client or an existing
booking being rescheduled. Confirmed:
developer.phorest.com/reference/checkappointmentavailability.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/AvailabilityRequest' }
responses:
'200':
description: Appointment availabilities listed.
content:
application/json:
schema:
type: object
properties:
availableSlots:
type: array
items: { $ref: '#/components/schemas/AvailabilitySlot' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
'500': { $ref: '#/components/responses/ServerError' }
/{businessId}/branch/{branchId}/booking:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
post:
operationId: createBooking
tags: [Bookings]
summary: Create a booking
description: >-
Creates a booking (one or more scheduled services) for a client.
Confirmed: developer.phorest.com/reference/createbooking.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/BookingInput' }
responses:
'201':
description: Booking created successfully.
content:
application/json:
schema: { $ref: '#/components/schemas/Booking' }
'400':
description: Booking data is invalid, unable to create a booking.
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
'500': { $ref: '#/components/responses/ServerError' }
/{businessId}/branch/{branchId}/booking/{bookingId}/cancel:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- name: bookingId
in: path
required: true
schema: { type: string }
post:
operationId: cancelBooking
tags: [Bookings]
summary: Cancel a booking
description: >-
Cancels a booking. Confirmed to exist:
developer.phorest.com/reference/cancelbooking; sub-path modeled by
convention.
responses:
'200':
description: Booking canceled successfully.
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/booking/{bookingId}/activate:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- name: bookingId
in: path
required: true
schema: { type: string }
post:
operationId: activateBooking
tags: [Bookings]
summary: Activate a reserved booking
description: >-
Activates a RESERVED booking, turning a temporary hold into an
ACTIVE booking. Confirmed to exist:
developer.phorest.com/reference/activatebooking; sub-path modeled
by convention.
responses:
'200':
description: Booking activated successfully.
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/booking/{bookingId}/note:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- name: bookingId
in: path
required: true
schema: { type: string }
post:
operationId: appendNoteToBooking
tags: [Bookings]
summary: Append a note to a booking
description: >-
Appends a service/colour note to an existing booking. Confirmed to
exist: developer.phorest.com/reference/appendnotetobooking;
sub-path modeled by convention.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
maxLength: 50000
responses:
'200':
description: Note appended successfully.
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/deposit-payment-link:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
post:
operationId: createDepositPaymentLink
tags: [Bookings]
summary: Create a deposit payment link
description: >-
Creates a hosted payment link so a client can pay a booking deposit
online. Confirmed to exist:
developer.phorest.com/reference/createdepositpaymentlink; sub-path
modeled by convention.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
bookingId: { type: string }
amount: { type: number }
responses:
'201':
description: Deposit payment link created successfully.
content:
application/json:
schema:
type: object
properties:
paymentLinkUrl: { type: string, format: uri }
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/staff:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
get:
operationId: getStaffList
tags: [Staff]
summary: List staff
description: >-
Lists staff for a branch, filterable by update time and archived
status. Confirmed: developer.phorest.com/reference/getstafflist.
parameters:
- name: updatedAfter
in: query
schema: { type: string }
- name: updatedBefore
in: query
schema: { type: string }
- name: fetch_archived
in: query
schema: { type: boolean }
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Staff listed successfully.
content:
application/json:
schema:
type: object
properties:
_embedded:
type: object
properties:
staffs:
type: array
items: { $ref: '#/components/schemas/Staff' }
'400': { $ref: '#/components/responses/BadRequest' }
'404': { $ref: '#/components/responses/NotFound' }
'429': { $ref: '#/components/responses/RateLimited' }
'500': { $ref: '#/components/responses/ServerError' }
/{businessId}/branch/{branchId}/staff/{staffId}:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- name: staffId
in: path
required: true
schema: { type: string }
get:
operationId: getStaff
tags: [Staff]
summary: Retrieve a staff member
description: >-
Retrieves a single staff member by ID. Confirmed to exist:
developer.phorest.com/reference/getstaff; sub-path modeled by
convention with the confirmed collection path.
responses:
'200':
description: The requested staff member.
content:
application/json:
schema: { $ref: '#/components/schemas/Staff' }
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/staff-work-time-table:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
get:
operationId: getStaffWorkTimeTables
tags: [Staff]
summary: List staff work time tables (rota)
description: >-
Returns staff work-time entries (rota) for a date range. This
endpoint does not support pagination and always returns all records
for the given range. Confirmed:
developer.phorest.com/reference/getstaffworktimetables.
parameters:
- name: from_date
in: query
required: true
schema: { type: string, format: date }
- name: to_date
in: query
required: true
schema: { type: string, format: date }
responses:
'200':
description: Staff work time tables listed successfully.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/StaffWorkTimeEntry' }
/{businessId}/branch/{branchId}/staff/{staffId}/break:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- name: staffId
in: path
required: true
schema: { type: string }
get:
operationId: getBreaks
tags: [Staff]
summary: List a staff member's breaks
description: >-
Lists breaks scheduled for a staff member. Confirmed to exist:
developer.phorest.com/reference/getbreaks; sub-path modeled by
convention.
responses:
'200':
description: Breaks listed successfully.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/StaffBreak' }
post:
operationId: createBreak
tags: [Staff]
summary: Create a staff break
description: >-
Creates a break on a staff member's rota. Confirmed to exist:
developer.phorest.com/reference/createbreak; sub-path modeled by
convention.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/StaffBreakInput' }
responses:
'201':
description: Break created successfully.
content:
application/json:
schema: { $ref: '#/components/schemas/StaffBreak' }
/{businessId}/branch/{branchId}/staff/{staffId}/break/{breakId}:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- name: staffId
in: path
required: true
schema: { type: string }
- name: breakId
in: path
required: true
schema: { type: string }
get:
operationId: getStaffBreak
tags: [Staff]
summary: Retrieve a staff break
description: >-
Retrieves a single break by ID. Confirmed to exist:
developer.phorest.com/reference/getstaffbreak; sub-path modeled by
convention.
responses:
'200':
description: The requested break.
content:
application/json:
schema: { $ref: '#/components/schemas/StaffBreak' }
'404': { $ref: '#/components/responses/NotFound' }
put:
operationId: updateBreak
tags: [Staff]
summary: Update a staff break
description: >-
Updates an existing break. Confirmed to exist:
developer.phorest.com/reference/updatebreak; sub-path modeled by
convention.
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/StaffBreakInput' }
responses:
'200':
description: Break updated successfully.
content:
application/json:
schema: { $ref: '#/components/schemas/StaffBreak' }
'404': { $ref: '#/components/responses/NotFound' }
delete:
operationId: deleteBreak
tags: [Staff]
summary: Delete a staff break
description: >-
Deletes a break. Confirmed to exist:
developer.phorest.com/reference/deletebreak; sub-path modeled by
convention.
responses:
'200':
description: Break deleted successfully.
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/service:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
get:
operationId: getServices
tags: [Services]
summary: List branch services
description: >-
Lists services offered at a branch, with price and duration data.
Modeled by convention: the item path GET
/{businessId}/branch/{branchId}/service/{serviceId} is confirmed at
developer.phorest.com/reference/getservice ("Retrieve a branch
service"); the bare collection path follows the same list/item
pattern confirmed across every other resource in this API.
parameters:
- name: category_id
in: query
schema: { type: string }
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Services listed successfully.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/Service' }
/{businessId}/branch/{branchId}/service/{serviceId}:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
- name: serviceId
in: path
required: true
schema: { type: string }
get:
operationId: getService
tags: [Services]
summary: Retrieve a branch service
description: >-
Retrieves a single branch service by ID, with an optional flag to
include its online category. Confirmed:
developer.phorest.com/reference/getservice.
parameters:
- name: fetch_online_category
in: query
schema: { type: boolean }
responses:
'200':
description: The requested service.
content:
application/json:
schema: { $ref: '#/components/schemas/Service' }
'404': { $ref: '#/components/responses/NotFound' }
/{businessId}/branch/{branchId}/service-category:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
get:
operationId: getServiceCategories
tags: [Services]
summary: List service categories
description: >-
Lists service categories for a branch. Confirmed:
developer.phorest.com/reference/getservicecategories.
parameters:
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Service categories listed successfully.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/ServiceCategory' }
/{businessId}/branch/{branchId}/package:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
get:
operationId: getServicePackages
tags: [Services]
summary: List service packages
description: >-
Lists bundled service packages for a branch, filterable by service
category. Confirmed:
developer.phorest.com/reference/getservicepackages.
parameters:
- name: category_id
in: query
schema: { type: string }
- $ref: '#/components/parameters/Size'
- $ref: '#/components/parameters/Page'
responses:
'200':
description: Service packages listed successfully.
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/ServicePackage' }
/{businessId}/branch/{branchId}/service-special-offer:
parameters:
- $ref: '#/components/parameters/BusinessId'
- $ref: '#/components/parameters/BranchId'
get:
operationId: getServiceSpecialOffers
tags: [Services]
summa
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/phorest/refs/heads/main/openapi/phorest-openapi.yml