> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightplace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# book_tour

> Submit a tour request using the renter's confirmed preferences.

`book_tour` requires a signed-in account. Call `get_tour_availability` first and
confirm the renter authorizes sending their contact details to the property.

## Input

```json theme={null}
{
  "listing_id": "listing-record-id",
  "slot": {
    "starts_at": "2026-10-02T10:00:00-04:00",
    "ends_at": "2026-10-02T10:30:00-04:00"
  },
  "mode": "slots",
  "tour_type": "in_person",
  "move_in_date": "2026-11-01"
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `listing_id` | string | Yes | Listing snapshot id returned by `search_listings`. |
| `slot` | object | For slots mode | Exact `starts_at` and `ends_at` from availability. |
| `mode` | string | No | `slots`, `request`, or `contact`; defaults to `slots` when a slot is supplied, otherwise `request`. |
| `tour_type` | string | No | Renter's preference: `in_person`, `self_guided`, or `video`. |
| `move_in_date` | date string | No | Renter-supplied YYYY-MM-DD. Never infer it from availability or the tour date. |
| `renter` | object | No | Defaults to signed-in account details. Override only at the user's request. Requires `first_name`, `last_name`, and `email`; `phone` is optional. |

For `request_only` or `contact_only` availability, omit the slot and use
`mode="request"` or `mode="contact"`. The worker must not select an arbitrary
appointment time. Required missing preferences or incompatible layout choices
stop the request for review instead of being filled with defaults.

## Output

```json theme={null}
{
  "tour_id": "book_01HZY...",
  "status": "submitted",
  "next_step_message": "Your tour request is in! The property will follow up by email to confirm the appointment.",
  "listing_id": "listing-record-id",
  "requested_start": "2026-10-02T10:00:00-04:00",
  "requested_end": "2026-10-02T10:30:00-04:00",
  "tour_type": "in_person",
  "mode": "slots"
}
```

`submitted` acknowledges the asynchronous request, not a confirmed appointment.
`get_tour_booking` returns its later status. `needs_review` can indicate missing
renter input, an unavailable requested option, or an unverified confirmation.
Read its message before retrying; an uncertain submission may already have reached
the property. The worker does not automatically resubmit.

## Limits and errors

brightplace limits active tour requests to 2 per renter email in a rolling
24-hour window. Additional active requests return `BOOKING_LIMIT_REACHED`.
Invalid input, including an invalid move-in date, returns a validation error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.