Phorest Services API

openapi: 3.0.3
info:
  title: Phorest Third-Party Appointments Services 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: Services
  description: Services, service categories, packages, and special offers.
paths:
  /{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
      summary: List service special offers
      description: 'Lists discounted service special offers for a branch, filterable by service category. Confirmed: developer.phorest.com/reference/getservices_1.'
      parameters:
      - name: category_id
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/Size'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Service special offers listed successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceSpecialOffer'
components:
  schemas:
    ServicePackage:
      type: object
      properties:
        packageId:
          type: string
        name:
          type: string
        categoryId:
          type: string
        price:
          type: number
        serviceIds:
          type: array
          items:
            type: string
    Service:
      type: object
      properties:
        serviceId:
          type: string
        name:
          type: string
        categoryId:
          type: string
        price:
          type: number
        durationMinutes:
          type: integer
        archived:
          type: boolean
    ServiceCategory:
      type: object
      properties:
        categoryId:
          type: string
        name:
          type: string
    ServiceSpecialOffer:
      type: object
      properties:
        offerId:
          type: string
        serviceId:
          type: string
        discountedPrice:
          type: number
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
  parameters:
    Page:
      name: page
      in: query
      description: Zero-indexed page number. Defaults to 0.
      schema:
        type: integer
        default: 0
        minimum: 0
    BusinessId:
      name: businessId
      in: path
      required: true
      description: The Phorest business (salon group) identifier.
      schema:
        type: string
    Size:
      name: size
      in: query
      description: Records per page. Max 100, defaults to 20.
      schema:
        type: integer
        default: 20
        maximum: 100
    BranchId:
      name: branchId
      in: path
      required: true
      description: The Phorest branch (location) identifier.
      schema:
        type: string
  responses:
    NotFound:
      description: The specified business, branch, or resource does not exist.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Username is `global/{email}`, using the email address Phorest associated with the granted API access. Password is the API password issued by Phorest support.