Appointment Endpoint

Appointments API access is read-only

Note: API Access is limited to Enterprise accounts and available upon request

---

Overview

The Appointments API allows Enterprise accounts to retrieve a paginated list of their appointments for a selected time period, including creation date/time, appointment start-end date/time, client, staff and service details.

Endpoint

POST https://my.simplespa.com/api/appointments.php

Authentication

You must include a valid Authorization header using your SimpleSpa API Key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Replace YOUR_API_KEY with your SimpleSpa Enterprise API Key.

Request Body

Field	Type	Required	Description
start	string	Yes	Start date in YYYY-MM-DD format
end	string	Yes	End date in YYYY-MM-DD format
status	integer	No	Appointment status code (optional)
page	integer	No	Page number (default: 1)
per_page	integer	No	Results per page (default: 1000 maximum)

Example Request

curl -X POST https://my.simplespa.com/api/appointments.php \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "start": "2025-04-01",
  "end": "2025-04-30",
  "status": 20,
  "page": 1,
  "per_page": 10
}'

Example Response

{
  "success": true,
  "appointments": [
    {
      "appointment_id": "1",
      "created_at": "2025-04-25 12:34:56",
      "start": "2025-04-30 09:00:00",
      "end": "2025-04-30 10:00:00",
      "status": {
        "code": 20,
        "description": "Confirmed"
      },
      "client": {
        "client_id": "1",
        "first_name": "John",
        "last_name": "Doe",
        "mobile": "555-1234",
        "email": "[e-mail]"
      },
      "service": {
        "service_id": "3",
        "service_name": "Deep Tissue Massage"
      },
      "staff": {
        "staff_id": "5",
        "staff_name": "Jane Therapist"
      }
    }
  ],
  "page": 1,
  "per_page": 10,
  "total_results": 50
}

Status Codes

Code	Description
0	New
5	Rebooked
7	Request
10	Online
12	Payment Due
15	Canceled
17	No-Show
20	Confirmed
22	Confirmed (No SMS)
25	Arrived
30	Paid
40	Completed

Notes

• Important: for polling-based setup, all new records will be fetched together, which could lead to duplication unless filtered appropriately, please keep a record of those that have been contacted if you are using this for notifications

• Limitation: Start/End date can range up to 92 days

• Pagination: Default per_page is 100 if not specified. Maximum allowed is 1000 per page.

• Rate Limiting: Please ensure reasonable usage to avoid throttling. It is recommended to poll no faster than once per minute.

⚠️ IMPORTANT: Never expose your private API key in client-side JavaScript. Always use secure, server-side code to handle sensitive credentials.