# POST /scheduling/voice/:event_type_id/slots

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

Voice-agent slot picker. Returns text/plain — a human-readable listing of available slots with a header block showing event type name, duration, host names, and description. Designed to be consumed verbatim by a Retell AI voice agent as a custom tool response. The AI never sees raw JSON or date ranges — just readable text it can speak directly. Slots are tagged with exact booking keys (slot:"YYYY-MM-DD HH:MM") for use in the /book endpoint.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `event_type_id` | path | uuid | yes | Event type UUID in the URL path |
| `preferred_day` | body | string | no | Natural-language day preference: "monday", "tomorrow", "asap", "this week", or YYYY-MM-DD. Past dates auto-advance to next occurrence of that weekday. Default: "asap". |
| `preferred_time` | body | string | no | Time preference: "morning", "afternoon", "evening", "around 2pm", "14:00", or omit for any time. |
| `state` | body | string | no | Customer state/territory (e.g. "NSW", "VIC", "QLD"). Used to auto-resolve timezone. Also accepted from Retell call dynamic variables. |
| `timezone` | body | string | no | IANA timezone override (e.g. "Australia/Perth"). Fallback if state is not provided. Default: Australia/Sydney. |

## Request example

```bash
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/scheduling/voice/{event_type_id}/slots" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "preferred_day": "monday", "preferred_time": "morning", "state": "NSW" }'
```

## Response example

```json
Offering: Free Consultation (30 min)
Host: Jane Smith
Description: A complimentary session to discuss your needs.

Monday 04/27: 9:00 AM [slot:2026-04-27 09:00], 9:30 AM [slot:2026-04-27 09:30], 10:00 AM [slot:2026-04-27 10:00]
Monday 05/04: 9:00 AM [slot:2026-05-04 09:00], 9:30 AM [slot:2026-05-04 09:30]

To book, pass the exact slot value (e.g. slot:"2026-04-28 09:00") with the caller's name and email.
```

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