# POST /scheduling/voice/:event_type_id/book

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

Voice-agent booking confirmation. Returns text/plain — a plain English sentence the AI reads to the caller to confirm the appointment. On success, includes event type name, duration, formatted start/end time, host names, description, Google Meet link, and booking ID. On failure, always returns HTTP 200 with a bolded warning the AI must not ignore — prevents the AI from falsely confirming a booking that failed. Supports Retell custom tool format: {"call":{...},"name":"tool_name","args":{...}}.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `event_type_id` | path | uuid | yes | Event type UUID in the URL path |
| `slot` | body | string | yes | Exact slot value from the /slots response, e.g. "2026-04-28 10:45". Unsubstituted Retell template variables ({{...}}) are detected and rejected with a fix message. |
| `name` | body | string | yes | Caller full name. Unsubstituted template variables rejected. |
| `email` | body | string | yes | Caller email for confirmation. Unsubstituted template variables rejected. |
| `phone` | body | string | no | Caller phone number (mobile, E.164 format) |
| `notes` | body | string | no | Any notes the caller provided |
| `state` | body | string | no | Customer state for timezone resolution (e.g. "VIC") |
| `timezone` | body | string | no | IANA timezone override. Default: Australia/Sydney. |

## Request example

```bash
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/scheduling/voice/{event_type_id}/book" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slot": "2026-04-28 10:00",
    "name": "Sarah Jones",
    "email": "sarah@example.com",
    "phone": "+61412345678",
    "state": "NSW"
  }'
```

## Response example

```json
Booked! Sarah Jones's Free Consultation (30 min) is confirmed for Monday, 28 April 2026 at 10:00 AM, ending at 10:30 AM. A confirmation has been sent to sarah@example.com.
Host: Jane Smith
Description: A complimentary session to discuss your needs.
Video link: https://meet.google.com/abc-defg-hij
Booking ID: b1c2d3e4-f5a6-...
```

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