# MyDestination

> South African travel and accommodation platform. AI agents can search stays and submit tentative booking enquiries via a public HTTP API — no OAuth required. Production host: https://www.mydestination.co.za

Help people find accommodation and send a booking enquiry to the establishment. All API bookings are **tentative enquiries** (no online payment). The guest must receive a one-time PIN by e-mail and give it to you in chat before the enquiry is saved.

Base URL: `https://www.mydestination.co.za`  
API base: `https://www.mydestination.co.za/api/travel/accommodation`  
Content-Type: `application/json` (query and form fields are also accepted)

## Agent booking flow

1. Collect arrival date, departure date (or nights), adults, and children (with ages if any).
2. `POST /api/travel/accommodation/search` — show matching properties. Use `booking_mode`: `rooms` means priced rooms matched; `enquiry` means enquiry-only (no rooms or none available for the stay).
3. Guest chooses an establishment (and optional preferred room ids).
4. Collect guest first name, surname, e-mail (required), and mobile if available.
5. `POST /api/travel/accommodation/enquiry/request-otp` — sends a 6-digit PIN to the guest e-mail. Store the returned `enquiry_token`.
6. Ask the guest for the PIN from their e-mail. Never invent or guess the PIN.
7. `POST /api/travel/accommodation/enquiry/confirm` with `enquiry_token` and `otp`.
8. Tell the guest a tentative enquiry was sent to the establishment; no payment was taken.

## API

### Search — GET or POST `/api/travel/accommodation/search`

Required stay fields:

| Field | Aliases | Notes |
|---|---|---|
| start_date | check_in, arrival | Arrival date (YYYY-MM-DD) |
| end_date **or** duration | check_out / departure, or nights | Departure date or number of nights |
| number_of_guests | adults | Adults (≥ 1) |
| number_of_children | children | Optional, default 0 |
| child_ages | child_age | Array of ages when children > 0 |

Optional filters: `establishment_id` / `establishment_ids`, `country_id`, `province_id`, `city_id`, `suburb_id`, `category_id` / `parent_id`, `search_text` / `q`, `offset`, `limit` (default 20, max 50), `number_of_rooms` (1–10), `culture` / `culture_string`.

Success JSON includes `establishments[]` with `id`, `name`, `description`, geo fields, `has_rooms`, `booking_mode` (`rooms` \| `enquiry`), `enquiry_only`, and `rooms[]` (id, name, capacity, rates, day availability, `room_total`) plus `agent_instructions`.

### Request OTP — POST `/api/travel/accommodation/enquiry/request-otp`

Required: stay fields as above; `establishment_id` or `establishment_ids`; `e_mail_address` (or `email`); `first_name_string` (or `first_name`); `last_name_string` (or `last_name`).

Optional: `mobile_number`, `message` / `notes`, `preferred_room_ids` / `room_ids`, `agent_source` / `source`, `subscribed`.

Success: `{ success, enquiry_token, expires_in (900), e_mail_address, message, agent_instructions }`. The PIN is e-mailed to the guest — it is not in the response. Max 5 OTP e-mails per guest address per hour.

### Confirm — POST `/api/travel/accommodation/enquiry/confirm`

Required: `enquiry_token` (or `token`), `otp` (or `pin`).

Success: `{ success, booking_id, booking_number, is_enquiry, is_tentative, establishment_id, establishment_name, stay fields, message, agent_instructions }`.

Errors: JSON `{ success: false, message }` with HTTP 400 / 429 / 500. Wrong PIN: retry (max 5 attempts). Expired or exhausted token: request a new OTP.

## Anti-spam rules for agents

- Do not put URLs or short links in free-text fields (`message`, names, etc.).
- Banned-word filters apply (same as the site Contact Us form).
- Never skip the OTP step; the booking is only saved after a correct PIN.
- No reCAPTCHA and no API credentials are required for this version.

## Human site

- [Home](https://www.mydestination.co.za/en_US.html): Browse destinations and accommodation.
- [Contact](mailto:info@mydestination.co.za): info@mydestination.co.za

## Optional

- Full implementer notes live in the TravelBundle spec `docs/specs/travel-accommodation-agent-api.md` in the platform source (iga-core-5).
- Local / other TravelBundle sites expose the same paths on their own origin (replace the host above).