Appointments
Book appointments from your own website, app or CRM, using the same rules as your booking page: team hours, business hours and holidays, blocked time, service variants, price rules and credits.
- Find a time with available slots for a service (and variant), optionally with a given team member.
- Book with
POST /v1/appointments(no payment asked), or withbook-with-paymentto collect payment online the way the booking page does. - Change with
reschedule(staff style: keeps the booked price) orreschedule-with-payment(customer style: the price follows the new time), andcancel.
A booking uses a matching active client credit and returns a credit object. Responses show bookedPrice, the variant and the priceRuleName applied, bookedFrom (API for bookings made here) and startTimeUTC. Booking new appointments needs the Bookings add-on; rescheduling and cancelling existing ones always work.
api.whautomate.comGet available slots
/v1/appointments/slotsLists the free start times for a service on a date (or the next three days), for any team member or one of them.
x-api-keystringrequiredtimezonestringAsia/Singapore. Defaults to the location timezone.staffIdstringdatestringlocationIdstringnextThreeDaysstringtrue to return slots for the date and the two days after it.serviceIdstringvariantIdstringdatestringrequiredtimezonestringrequiredslotsobject[]requiredcurl -X GET "https://api.whautomate.com/v1/appointments/slots?locationId=Le6dWjQF9K&serviceId=NzzoDETgKg&staffId=XrHPepEL8A&date=2026-11-09&timezone=Asia%2FSingapore" \
-H "x-api-key: YOUR_API_KEY"
[
{
"date": "2026-11-08T16:00:00.000Z",
"slots": [
{
"startTime": "09:00 AM",
"endTime": "09:45 AM",
"startTimeUTC": "2026-11-09T01:00:00.000Z",
"endTimeUTC": "2026-11-09T01:45:00.000Z"
},
{
"startTime": "09:45 AM",
"endTime": "10:30 AM",
"startTimeUTC": "2026-11-09T01:45:00.000Z",
"endTimeUTC": "2026-11-09T02:30:00.000Z"
},
{
"startTime": "10:30 AM",
"endTime": "11:15 AM",
"startTimeUTC": "2026-11-09T02:30:00.000Z",
"endTimeUTC": "2026-11-09T03:15:00.000Z"
}
]
}
]
Search appointments
/v1/appointmentsLists appointments in a date range, filtered by location, team member or client.
x-api-keystringrequiredlimitintegerstaffIdstringclientIdstringendDatestringlocationIdstringpageintegerstartDatestringidstringlocationobjectrequiredclientobjectrequiredstaffobjectrequireddatestringrequiredtimestringrequiredtimezonestringstartTimeUTCstringstartTimestringendTimeUTCstringendTimestringserviceobjectrequiredvariantobjectThe service variant a booking or class was made with. Only returned when the service has variants.
bookedPricenumberpriceRuleNamestringaddOnServicesobject[]bookedFromstringstatusstringappointmentTypestringpaymentStatusstringcreditobjectnotesstringcreatedAtstringupdatedAtstringcurl -X GET "https://api.whautomate.com/v1/appointments?clientId=FLT22gHGml&startDate=2026-10-29&endDate=2026-12-09&limit=3" \
-H "x-api-key: YOUR_API_KEY"
[
{
"id": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "FLT22gHGml",
"fullName": "Priya Nair"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"timezone": "Asia/Singapore",
"date": "2026-11-09",
"time": "09:00 AM",
"startTimeUTC": "2026-11-09T01:00:00.000Z",
"startTime": "2026-11-09T09:00:00.000Z",
"endTimeUTC": "2026-11-09T01:45:00.000Z",
"endTime": "2026-11-09T09:45:00.000Z",
"service": {
"id": "NzzoDETgKg",
"name": "Physiotherapy Consultation",
"durationMinutes": 45,
"sellingPrice": 130
},
"bookedPrice": 130,
"addOnServices": [],
"bookedFrom": "API",
"status": "Booked",
"appointmentType": "LOCATION_VISIT",
"notes": "Lower back pain after long runs.",
"paymentStatus": "",
"createdAt": "2026-10-29T12:40:16.176Z",
"updatedAt": "2026-10-29T12:40:16.176Z"
}
]
Get an appointment
/v1/appointments/{appointmentId}Gets one appointment by id.
x-api-keystringrequiredappointmentIdstringrequiredidstringlocationobjectrequiredclientobjectrequiredstaffobjectrequireddatestringrequiredtimestringrequiredtimezonestringstartTimeUTCstringstartTimestringendTimeUTCstringendTimestringserviceobjectrequiredvariantobjectThe service variant a booking or class was made with. Only returned when the service has variants.
bookedPricenumberpriceRuleNamestringaddOnServicesobject[]bookedFromstringstatusstringappointmentTypestringpaymentStatusstringcreditobjectnotesstringcreatedAtstringupdatedAtstringcurl -X GET "https://api.whautomate.com/v1/appointments/FmNtn5W1AG" \
-H "x-api-key: YOUR_API_KEY"
{
"id": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "FLT22gHGml",
"fullName": "Priya Nair"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"timezone": "Asia/Singapore",
"date": "2026-11-09",
"time": "09:00 AM",
"startTimeUTC": "2026-11-09T01:00:00.000Z",
"startTime": "2026-11-09T09:00:00.000Z",
"endTimeUTC": "2026-11-09T01:45:00.000Z",
"endTime": "2026-11-09T09:45:00.000Z",
"service": {
"id": "NzzoDETgKg",
"name": "Physiotherapy Consultation",
"durationMinutes": 45,
"sellingPrice": 130
},
"bookedPrice": 130,
"addOnServices": [],
"bookedFrom": "API",
"status": "Booked",
"appointmentType": "LOCATION_VISIT",
"notes": "Lower back pain after long runs.",
"paymentStatus": "",
"createdAt": "2026-10-29T12:40:16.176Z",
"updatedAt": "2026-10-29T12:40:16.176Z"
}
Book an appointment
/v1/appointmentsBooks an appointment straight away, without asking for payment. Uses the client's credits when they have a matching grant.
x-api-keystringrequiredclientobjectrequiredlocationobjectrequiredserviceobjectrequireddatestringrequiredtimestringrequiredstartTimeUTCstringoverrideTimeSlotValidationbooleanstaffobjecttimezonestringnotesstringaddOnServicesobject[]idstringlocationobjectrequiredclientobjectrequiredstaffobjectrequireddatestringrequiredtimestringrequiredtimezonestringstartTimeUTCstringstartTimestringendTimeUTCstringendTimestringserviceobjectrequiredvariantobjectThe service variant a booking or class was made with. Only returned when the service has variants.
bookedPricenumberpriceRuleNamestringaddOnServicesobject[]bookedFromstringstatusstringappointmentTypestringpaymentStatusstringcreditobjectnotesstringcreatedAtstringupdatedAtstringErrors
| Status | Error | Meaning |
|---|---|---|
| 404 | Client not found / Service not found | The client, location or service is not in your account. |
| 409 | No slots available ... | The time is no longer free or no team member is available. Get fresh slots. |
curl -X POST "https://api.whautomate.com/v1/appointments" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client": {
"id": "FLT22gHGml"
},
"location": {
"id": "Le6dWjQF9K"
},
"service": {
"id": "NzzoDETgKg"
},
"staff": {
"id": "XrHPepEL8A"
},
"date": "2026-11-09",
"time": "09:00 AM",
"timezone": "Asia/Singapore",
"notes": "Lower back pain after long runs."
}'
{
"id": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "FLT22gHGml",
"fullName": "Priya Nair"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"timezone": "Asia/Singapore",
"date": "2026-11-09",
"time": "09:00 AM",
"startTimeUTC": "2026-11-09T01:00:00.000Z",
"startTime": "2026-11-09T09:00:00.000Z",
"endTimeUTC": "2026-11-09T01:45:00.000Z",
"endTime": "2026-11-09T09:45:00.000Z",
"service": {
"id": "NzzoDETgKg",
"name": "Physiotherapy Consultation",
"durationMinutes": 45,
"sellingPrice": 130
},
"bookedPrice": 130,
"addOnServices": [],
"bookedFrom": "API",
"status": "Booked",
"appointmentType": "LOCATION_VISIT",
"notes": "Lower back pain after long runs.",
"paymentStatus": "",
"createdAt": "2026-10-29T12:40:16.176Z",
"updatedAt": "2026-10-29T12:40:16.176Z",
"credit": null
}
curl -X POST "https://api.whautomate.com/v1/appointments" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client": {
"fullName": "Sophie Tan",
"countryCode": "+65",
"phone": "93318826"
},
"location": {
"id": "Le6dWjQF9K"
},
"service": {
"id": "NzzoDETgKg"
},
"staff": {
"id": "XrHPepEL8A"
},
"date": "2026-11-09",
"time": "03:45 PM",
"timezone": "Asia/Singapore"
}'
{
"id": "UBS9QSITqV",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "NfXfZ6Oj95",
"fullName": "Sophie Tan"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"timezone": "Asia/Singapore",
"date": "2026-11-09",
"time": "03:45 PM",
"startTimeUTC": "2026-11-09T07:45:00.000Z",
"startTime": "2026-11-09T15:45:00.000Z",
"endTimeUTC": "2026-11-09T08:30:00.000Z",
"endTime": "2026-11-09T16:30:00.000Z",
"service": {
"id": "NzzoDETgKg",
"name": "Physiotherapy Consultation",
"durationMinutes": 45,
"sellingPrice": 130
},
"bookedPrice": 130,
"addOnServices": [],
"bookedFrom": "API",
"status": "Booked",
"appointmentType": "LOCATION_VISIT",
"paymentStatus": "",
"createdAt": "2026-10-29T12:40:16.918Z",
"updatedAt": "2026-10-29T12:40:16.918Z",
"credit": null
}
Book an appointment with payment
/v1/appointments/book-with-paymentBooks like the customer booking page does. If the service accepts payment online and the client has no credits to use, nothing is booked yet: the slot is held, a payment link is returned and the appointment is created when the client pays. The link expires with the hold (expiresAt, usually after 10 minutes). Otherwise the appointment is booked straight away. Services with a deposit ask for the deposit only. Use POST /v1/appointments to book without asking for payment.
x-api-keystringrequiredclientobjectrequiredExisting client by id, or a new or matched client by fullName + countryCode + phone.
locationobjectrequiredserviceobjectrequiredstaffobjectdatestringrequiredtimestringrequiredstartTimeUTCstringtimezonestringnotesstringbookingTypestring (enum)APPOINTMENT, CLASS.statusstring (enum)PAYMENT_PENDING, BOOKED, WAITLISTED.paymentRequiredbooleancurrencystringpaymentobjectserviceobjectclassIdstringappointmentobjectclassParticipantobjectcurl -X POST "https://api.whautomate.com/v1/appointments/book-with-payment" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client": {
"id": "FLT22gHGml"
},
"location": {
"id": "Le6dWjQF9K"
},
"service": {
"id": "THF7D9KbDa"
},
"staff": {
"id": "ZxkrjyVgDE"
},
"date": "2026-11-09",
"time": "02:00 PM",
"timezone": "Asia/Singapore"
}'
{
"bookingType": "APPOINTMENT",
"status": "PAYMENT_PENDING",
"paymentRequired": true,
"currency": "SGD",
"payment": {
"orderId": "g2wCSDafpo",
"paymentLink": "https://app.whautomate.com/p/g2wCSDafpo?redirect=true",
"currency": "SGD",
"subTotal": 135,
"taxAmount": 0,
"totalAmount": 135,
"expiresAt": "2026-10-29T13:10:18.643Z",
"expiresInMinutes": 30,
"message": "The payment link expires in 30 minutes. The slot is held until then; the booking is confirmed once payment succeeds. After that the client needs to book again."
},
"service": {
"id": "THF7D9KbDa",
"name": "Deep Tissue Massage"
}
}
curl -X POST "https://api.whautomate.com/v1/appointments/book-with-payment" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"client": {
"id": "iqf8hDweF6"
},
"location": {
"id": "Le6dWjQF9K"
},
"service": {
"id": "hHuMZsZn7t"
},
"staff": {
"id": "XrHPepEL8A"
},
"date": "2026-11-09",
"time": "03:00 PM",
"timezone": "Asia/Singapore"
}'
{
"bookingType": "APPOINTMENT",
"status": "BOOKED",
"paymentRequired": false,
"currency": "SGD",
"payment": null,
"appointment": {
"id": "lVsORgHaGl",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "iqf8hDweF6",
"fullName": "Daniel Wong"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"service": {
"id": "hHuMZsZn7t",
"name": "Sports Recovery Session",
"durationMinutes": 30
},
"bookedPrice": 75,
"timezone": "Asia/Singapore",
"date": "2026-11-09",
"time": "03:00 PM",
"startTimeUTC": "2026-11-09T07:00:00.000Z",
"endTimeUTC": "2026-11-09T07:30:00.000Z",
"status": "Booked"
}
}
Reschedule an appointment
/v1/appointments/rescheduleMoves an appointment to a new time, as staff do in the app. The booked price stays the same.
x-api-keystringrequiredappointmentIdstringrequiredlocationobjectrequireddatestringrequiredtimestringrequiredtimezonestringidstringlocationobjectrequiredclientobjectrequiredstaffobjectrequireddatestringrequiredtimestringrequiredtimezonestringstartTimeUTCstringstartTimestringendTimeUTCstringendTimestringserviceobjectrequiredvariantobjectThe service variant a booking or class was made with. Only returned when the service has variants.
bookedPricenumberpriceRuleNamestringaddOnServicesobject[]bookedFromstringstatusstringappointmentTypestringpaymentStatusstringcreditobjectnotesstringcreatedAtstringupdatedAtstringcurl -X POST "https://api.whautomate.com/v1/appointments/reschedule" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"appointmentId": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K"
},
"date": "2026-11-09",
"time": "12:00 PM",
"timezone": "Asia/Singapore"
}'
{
"id": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "FLT22gHGml",
"fullName": "Priya Nair"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"timezone": "Asia/Singapore",
"date": "2026-11-09",
"time": "12:00 PM",
"startTimeUTC": "2026-11-09T04:00:00.000Z",
"startTime": "2026-11-09T12:00:00.000Z",
"endTimeUTC": "2026-11-09T04:45:00.000Z",
"endTime": "2026-11-09T12:45:00.000Z",
"service": {
"id": "NzzoDETgKg",
"name": "Physiotherapy Consultation",
"durationMinutes": 45,
"sellingPrice": 130
},
"bookedPrice": 130,
"addOnServices": [],
"bookedFrom": "API",
"status": "Rescheduled",
"appointmentType": "LOCATION_VISIT",
"notes": "Lower back pain after long runs.",
"paymentStatus": "",
"createdAt": "2026-10-29T12:40:16.176Z",
"updatedAt": "2026-10-29T12:40:17.783Z"
}
Reschedule an appointment with repricing
/v1/appointments/reschedule-with-paymentCustomer-style reschedule: the price follows the new time (weekend, after-hours rules). Dearer without acceptedPriceDifference: 409 with code PRICE_CONFIRMATION_REQUIRED and priceChange, nothing changes. Dearer on a booking paid in full: the new time is held and a payment link for the extra is returned; the booking moves when it is paid. Otherwise it moves at once (cheaper: the surplus goes to the client's funds or reduces the balance; dearer: added to the balance due). POST /v1/appointments/reschedule (staff) keeps the booked price.
A dearer time without acceptedPriceDifference answers 409 with code PRICE_CONFIRMATION_REQUIRED and a priceChange to show the client; nothing changes until you send it again with the difference accepted.
x-api-keystringrequiredappointmentIdstringrequireddatestringrequiredtimestringrequiredtimezonestringlocationobjectrequiredstaffobjectOptional: switch to this staff member (id, or any)
acceptedPriceDifferencenumberstatusstring (enum)RESCHEDULED, PAYMENT_PENDING.paymentRequiredbooleanappointmentIdstringpaymentobjectpriceChangeobjectWhat the new time costs compared with the booking (amounts include tax, as on the invoice).
appointmentobjectThe moved appointment (status RESCHEDULED)
curl -X POST "https://api.whautomate.com/v1/appointments/reschedule-with-payment" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"appointmentId": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K"
},
"date": "2026-11-10",
"time": "09:00 AM",
"timezone": "Asia/Singapore"
}'
{
"status": "RESCHEDULED",
"paymentRequired": false,
"payment": null,
"appointment": {
"id": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "FLT22gHGml",
"fullName": "Priya Nair"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"service": {
"id": "NzzoDETgKg",
"name": "Physiotherapy Consultation",
"durationMinutes": 45
},
"bookedPrice": 130,
"timezone": "Asia/Singapore",
"date": "2026-11-10",
"time": "09:00 AM",
"startTimeUTC": "2026-11-10T01:00:00.000Z",
"endTimeUTC": "2026-11-10T01:45:00.000Z",
"status": "Rescheduled"
}
}
Cancel an appointment
/v1/appointments/cancelCancels an appointment. Credits used for it are given back.
x-api-keystringrequiredappointmentIdstringrequiredlocationobjectrequiredcancellationReasonstringidstringlocationobjectclientobjectstaffobjecttimezonestringdatestringtimestringstartTimeUTCstringstartTimestringendTimeUTCstringendTimestringserviceobjectbookedPriceintegeraddOnServicesstring[]bookedFromstringstatusstringappointmentTypestringnotesstringpaymentStatusstringcreatedAtstringupdatedAtstringcurl -X POST "https://api.whautomate.com/v1/appointments/cancel" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"appointmentId": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K"
},
"cancellationReason": "Client asked to cancel."
}'
{
"id": "FmNtn5W1AG",
"location": {
"id": "Le6dWjQF9K",
"title": "Serene Wellness Studio"
},
"client": {
"id": "FLT22gHGml",
"fullName": "Priya Nair"
},
"staff": {
"id": "XrHPepEL8A",
"name": "Wei Jie Tan"
},
"timezone": "Asia/Singapore",
"date": "2026-11-10",
"time": "09:00 AM",
"startTimeUTC": "2026-11-10T01:00:00.000Z",
"startTime": "2026-11-10T09:00:00.000Z",
"endTimeUTC": "2026-11-10T01:45:00.000Z",
"endTime": "2026-11-10T09:45:00.000Z",
"service": {
"id": "NzzoDETgKg",
"name": "Physiotherapy Consultation",
"durationMinutes": 45,
"sellingPrice": 130
},
"bookedPrice": 130,
"addOnServices": [],
"bookedFrom": "API",
"status": "Cancelled",
"appointmentType": "LOCATION_VISIT",
"notes": "Lower back pain after long runs. Reason for cancellation: Client asked to cancel.",
"paymentStatus": "",
"createdAt": "2026-10-29T12:40:16.176Z",
"updatedAt": "2026-10-29T12:40:33.133Z"
}