book_tour

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

{
  "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

{
  "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.

brightplace Connect

Tool Reference

Security and Policy

Input

Output

Limits and errors

​Input

​Output

​Limits and errors

Input

Output

Limits and errors