Booking API documentation

Request notes

• No query parameters are required.
• If no booking settings row exists, the API returns the documented default values.

Response

{
  "name": "North Elm Studio",
  "description": "Modern color and styling appointments",
  "category": "Salon",
  "logoUrl": "https://cdn.example.com/logo.png",
  "phone": "(555) 555-1234",
  "address": "123 Main St",
  "timezone": "America/Chicago",
  "hours": [
    {
      "day": "Sunday",
      "isOpen": true,
      "openTime": "09:00:00",
      "closeTime": "19:00:00"
    }
  ],
  "bookingSettings": {
    "bookingLeadTimeMinutes": 60,
    "bookingWindowDays": 7,
    "slotIntervalMinutes": 30
  },
  "bookingPage": {
    "showStaffSelection": true,
    "showServicePrices": true,
    "showServiceDuration": true,
    "requireCustomerEmail": true
  }
}

• hours[*].day uses the full English weekday name.
• openTime and closeTime may be null when the business is closed.

Request notes

• No query parameters are required.
• id, name, description, and photoUrl are always present when the service is returned.

Response

{
  "categories": [
    {
      "categoryId": "3df6c08d-1111-2222-3333-a0ce0c2d8f11",
      "categoryName": "Cuts",
      "services": [
        {
          "id": "2f564239-1111-2222-3333-fdc2233f6c7d",
          "name": "Fade",
          "description": "Classic fade with clean finish",
          "photoUrl": null,
          "durationMinutes": 45,
          "price": 35
        }
      ]
    }
  ]
}

• When prices are hidden, price is omitted instead of set to zero.
• When service duration is hidden, durationMinutes is omitted.

Request notes

• Path: GET /booking/staff or GET /booking/staff?serviceId=<uuid>.
• For any professional, call GET /booking/dates, GET /booking/slots, and POST /booking/appointments with userId omitted or userId=any.

Response

{
  "staff": [
    {
      "id": "8caa3f5f-1111-2222-3333-bdfd8ef3f743",
      "fullName": "Maria Gomez",
      "jobTitle": "Lead stylist",
      "about": null,
      "photoUrl": null,
      "nextAvailable": null
    }
  ]
}

• jobTitle, about, photoUrl, and color may be null.
• nextAvailable is reserved and currently null.

Response

{
  "from": "2026-01-15",
  "dates": [
    { "date": "2026-01-15", "slotCount": 4 },
    { "date": "2026-01-17", "slotCount": 2 }
  ]
}

• slotCount is based on slot start times that are actually available, using the business slot interval.
• Returns 400 when serviceId is missing or from is not in YYYY-MM-DD format.

Response

{
  "date": "2026-01-15",
  "slots": [
    { "time": "10:00", "available": true },
    { "time": "10:30", "available": false },
    { "time": "11:00", "available": true }
  ]
}

• Returns 400 when date or serviceId is missing.
• An empty slots array means the day is closed, off-limits, outside the booking window, or fully unavailable.

Response

{
  "success": true,
  "booking": {
    "id": "5a43e6ce-1111-2222-3333-39f7d1a233fb",
    "confirmationCode": "BN-1234",
    "serviceName": "Fade",
    "servicePrice": 35,
    "appointmentDate": "2026-01-20",
    "appointmentTime": "10:00",
    "durationMinutes": 45,
    "staffName": "Maria Gomez",
    "businessName": "North Elm Studio",
    "businessAddress": "123 Main St",
    "guestName": "Jordan Smith",
    "guestEmail": "jordan@example.com",
    "status": "confirmed"
  }
}

• status is confirmed or pending depending on auto_confirm_bookings.
• Use 409 responses as a signal to re-fetch /booking/slots and ask the customer to choose again.

Error cases

Response

{
  "id": "5a43e6ce-1111-2222-3333-39f7d1a233fb",
  "confirmationCode": "BN-1234",
  "serviceName": "Fade",
  "servicePrice": 35,
  "appointmentDate": "2026-01-20",
  "appointmentTime": "10:00:00",
  "durationMinutes": 45,
  "staffName": "Maria Gomez",
  "status": "pending",
  "guestName": "Jordan Smith",
  "guestEmail": "jordan@example.com",
  "businessName": "North Elm Studio",
  "businessAddress": "123 Main St"
}

• appointmentTime is returned in the database form, often HH:MM:SS.
• Returns 404 with { "success": false, "error": "Not found" } when the appointment does not belong to the business.

Response

{
  "success": true,
  "status": "cancelled"
}

• Returns 404 if the appointment is missing, outside the valid range, or not cancellable.

Response

{}

• Returns HTTP 200 with an empty JSON body.
• CORS allows Content-Type and x-private-key.