Appointments API

The Appointments API allows you to programmatically create and manage bookings in Bookwell.

List Appointments

GET

/v1/appointments

Retrieve a list of appointments

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (confirmed, cancelled, completed)
`date_from`	string	Start date (ISO 8601)
`date_to`	string	End date (ISO 8601)
`therapist_id`	string	Filter by therapist
`customer_id`	string	Filter by customer
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20, max: 100)

Example Request

curl "https://api.bookwell.app/v1/appointments?status=confirmed&date_from=2025-01-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "apt_abc123",
      "service_id": "srv_xyz789",
      "service_name": "60-Minute Massage",
      "customer_id": "cus_def456",
      "customer_name": "Jane Smith",
      "therapist_id": "thr_ghi012",
      "therapist_name": "Sarah Johnson",
      "start_time": "2025-01-15T10:00:00Z",
      "end_time": "2025-01-15T11:00:00Z",
      "status": "confirmed",
      "price": 9500,
      "currency": "usd",
      "created_at": "2025-01-10T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}

Get Appointment

GET

/v1/appointments/:id

Retrieve a single appointment

Path Parameters

Parameter	Type	Description
`id`	string	The appointment ID

Example Request

curl https://api.bookwell.app/v1/appointments/apt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "id": "apt_abc123",
    "service_id": "srv_xyz789",
    "service_name": "60-Minute Massage",
    "customer_id": "cus_def456",
    "customer": {
      "id": "cus_def456",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "phone": "+1234567890"
    },
    "therapist_id": "thr_ghi012",
    "therapist_name": "Sarah Johnson",
    "start_time": "2025-01-15T10:00:00Z",
    "end_time": "2025-01-15T11:00:00Z",
    "status": "confirmed",
    "price": 9500,
    "currency": "usd",
    "notes": "Prefers firm pressure",
    "addons": [],
    "payment_status": "paid",
    "created_at": "2025-01-10T14:30:00Z",
    "updated_at": "2025-01-10T14:30:00Z"
  }
}

Create Appointment

POST

/v1/appointments

Create a new appointment

Request Body

Field	Type	Required	Description
`service_id`	string	Yes	The service to book
`therapist_id`	string	No	Specific therapist (or auto-assign)
`start_time`	string	Yes	Appointment start (ISO 8601)
`customer`	object	Yes	Customer information
`customer.email`	string	Yes	Customer email
`customer.name`	string	Yes	Customer name
`customer.phone`	string	No	Customer phone
`notes`	string	No	Booking notes
`addons`	array	No	Add-on service IDs
`send_confirmation`	boolean	No	Send email confirmation (default: true)

Example Request

curl https://api.bookwell.app/v1/appointments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "srv_xyz789",
    "therapist_id": "thr_ghi012",
    "start_time": "2025-01-15T10:00:00Z",
    "customer": {
      "email": "jane@example.com",
      "name": "Jane Smith",
      "phone": "+1234567890"
    },
    "notes": "First visit, prefers firm pressure"
  }'

Example Response

{
  "data": {
    "id": "apt_abc123",
    "service_id": "srv_xyz789",
    "service_name": "60-Minute Massage",
    "customer_id": "cus_def456",
    "therapist_id": "thr_ghi012",
    "start_time": "2025-01-15T10:00:00Z",
    "end_time": "2025-01-15T11:00:00Z",
    "status": "confirmed",
    "price": 9500,
    "currency": "usd",
    "notes": "First visit, prefers firm pressure",
    "created_at": "2025-01-10T14:30:00Z"
  }
}

Customer Handling

If the email matches an existing customer, they'll be linked. Otherwise, a new customer record is created.

Update Appointment

PATCH

/v1/appointments/:id

Update an existing appointment

Request Body

Field	Type	Description
`start_time`	string	New start time (ISO 8601)
`therapist_id`	string	Reassign to different therapist
`notes`	string	Update notes
`status`	string	Update status

Example Request

curl -X PATCH https://api.bookwell.app/v1/appointments/apt_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_time": "2025-01-15T14:00:00Z",
    "notes": "Rescheduled per customer request"
  }'

Example Response

{
  "data": {
    "id": "apt_abc123",
    "start_time": "2025-01-15T14:00:00Z",
    "end_time": "2025-01-15T15:00:00Z",
    "status": "confirmed",
    "notes": "Rescheduled per customer request",
    "updated_at": "2025-01-12T09:15:00Z"
  }
}

Cancel Appointment

POST

/v1/appointments/:id/cancel

Cancel an appointment

Request Body

Field	Type	Description
`reason`	string	Cancellation reason
`notify_customer`	boolean	Send notification (default: true)
`refund`	boolean	Process refund (default: per policy)

Example Request

curl -X POST https://api.bookwell.app/v1/appointments/apt_abc123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Customer request",
    "notify_customer": true,
    "refund": true
  }'

Example Response

{
  "data": {
    "id": "apt_abc123",
    "status": "cancelled",
    "cancelled_at": "2025-01-12T10:00:00Z",
    "cancellation_reason": "Customer request",
    "refund_amount": 9500,
    "refund_status": "processing"
  }
}

Check Availability

GET

/v1/availability

Get available time slots

Query Parameters

Parameter	Type	Required	Description
`service_id`	string	Yes	Service to check
`date`	string	Yes	Date to check (YYYY-MM-DD)
`therapist_id`	string	No	Specific therapist
`duration`	integer	No	Override duration (minutes)

Example Request

curl "https://api.bookwell.app/v1/availability?service_id=srv_xyz789&date=2025-01-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": {
    "date": "2025-01-15",
    "service_id": "srv_xyz789",
    "slots": [
      {
        "start_time": "2025-01-15T09:00:00Z",
        "end_time": "2025-01-15T10:00:00Z",
        "therapist_id": "thr_ghi012",
        "therapist_name": "Sarah Johnson"
      },
      {
        "start_time": "2025-01-15T11:00:00Z",
        "end_time": "2025-01-15T12:00:00Z",
        "therapist_id": "thr_ghi012",
        "therapist_name": "Sarah Johnson"
      },
      {
        "start_time": "2025-01-15T10:00:00Z",
        "end_time": "2025-01-15T11:00:00Z",
        "therapist_id": "thr_jkl345",
        "therapist_name": "Mike Brown"
      }
    ]
  }
}

Webhooks for Appointments

Subscribe to appointment events:

appointment.created - New booking
appointment.updated - Booking modified
appointment.cancelled - Booking cancelled
appointment.completed - Service completed

See Webhooks for setup instructions.

Error Handling

Common appointment errors:

Code	Description
`slot_unavailable`	Requested time is no longer available
`service_not_found`	Invalid service ID
`therapist_unavailable`	Therapist not available at requested time
`customer_blocked`	Customer is blocked from booking
`past_booking`	Cannot book in the past

See Errors for complete error reference.

Next Steps

Services API

Retrieve service information.

Webhooks

Receive real-time notifications.

Create, retrieve, and manage appointments via the Bookwell API.

Customer Handling

Services API

Webhooks