Appointment Status

Note: API Beta Access, see API Terms of Use

---

Overview

The Appointment Status Update API allows approved Enterprise accounts to update the status of an existing appointment using the appointment ID.

This endpoint is designed for integrations that need to:

• Confirm appointments

• Cancel appointments

• Sync appointment status updates from external systems

• Automate workflows triggered by appointment changes

Status changes update the internal appointment tables and create corresponding status update records used for notifications and audit logs.

Endpoint

POST https://my.simplespa.com/api/v1/write/appointment-status.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. API Key Mode must be 2 (Write) or 3 (Read + Write) to use this endpoint.

Request Body

Parameter	Type	Required	Description
appointment_id	string	Required	The appointment ID.
status	integer	Required	The new appointment status code (see Status Codes table below).
reason	string	Optional	Optional text describing why the status is being changed (used for logging/audit purposes, not displayed).

Example Request

curl -X POST https://my.simplespa.com/api/v1/write/appointment-status.php \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
  "status": 20,
  "reason": "client_confirmed_via_external_system"
}'

Example Response

{
  "success": true,
  "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
  "appointment_id_raw": 12345,
  "old_status": 10,
  "new_status": 20,
  "reason": "client_confirmed_via_external_system"
}

Example 1 — Mark Appointment as Confirmed

curl -X POST https://my.simplespa.com/api/v1/write/appointment-status.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
    "status": 20,
    "reason": "client_confirmed_via_external_system"
  }'

Example 2 — Cancel Appointment

curl -X POST https://my.simplespa.com/api/v1/write/appointment-status.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_id": "e3b0c44298fc1c149afbf4c8996fb924",
    "status": 15,
    "reason": "cancelled_by_client"
  }'

Status Codes

These status codes align with the main Appointment Endpoint:

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

• This endpoint only updates status for an existing appointment. It does not create appointments or change times, staff, or services.

• Rate Limiting: This endpoint is strictly rate limited. Excessive updates may result in HTTP 429 responses. We recommend keeping status updates to no more than 10 requests per minute per API key.

• Pagination is not applicable for this endpoint (single appointment update per call).

⚠️ IMPORTANT: Never expose your private API key in client-side JavaScript, mobile apps, or public code repositories. Always perform API calls from secure, server-side code.