# POST /scheduling/voice/cancel-booking

**Resource:** [Scheduling Bookings](./scheduling-bookings.md)  
**Scopes:** `scheduling:write`  
**Write operation:** yes

Voice-agent booking cancellation. Returns text/plain. Resolves the caller by phone number (from args.phone, or Retell call envelope from_number/to_number as fallback), then cancels the matching upcoming booking. When the caller has multiple upcoming bookings, omit booking_selector on the first call to receive a numbered disambiguation list; re-fire with the caller's choice to execute the cancellation. Always returns HTTP 200 - failures begin with "BOOKING CANCELLATION FAILED:" and must not be read as confirmations.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `phone` | body | string | no | Caller phone number (E.164 or AU local format). Falls back to Retell call envelope from_number (inbound) or to_number (outbound). |
| `booking_selector` | body | string | no | Which booking to cancel when the caller has multiple upcoming. Accepts: 1-based integer index (from disambiguation list), booking UUID prefix, or partial event type name substring. Omit to auto-select when only one booking exists, or to trigger the disambiguation list when multiple exist. |
| `reason` | body | string | no | Cancellation reason stored on the booking record. |

## Request example

```bash
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/scheduling/voice/cancel-booking" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "args": { "phone": "+61412345678", "booking_selector": "1", "reason": "caller request" } }'
```

## Response example

```json
Cancelled! Your Free Consultation (30 min) on Monday, 28 April 2026 at 10:00 AM has been cancelled.
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`