Viewings

What you can do through the API

Permissions

• Hours, schedules, open houses, reports and projects need listings:read to read and listings:write to change.
• Anything about a person also needs the requests’ permissions: leads:read to see the client who booked (visitor), a client added by hand, the attendees of an open house and the note from “How did it go?”, and leads:write to add a client or an attendee, to work on the attendance sheet and to record how a viewing went. A key without leads:read gets visitor: null and does not see the attendance sheet. The listing’s report holds no people, so any key with listings:read reads it.
• A key sees the viewings its account runs in the app: the listings it manages, those whose viewings were handed to it and, at a developer, the bookings that reached it as a consultant. Outside them the answer is 404.

How long the data is kept

What stays in the app only

• The client’s side: booking, holding the hour while they sign in, the cancelling and moving they do, “I’m coming too” for an open house, the form at the door, their private note, “My viewings”, the calendar file and the “Still coming?” link in the email. Your key works for the person who publishes the listing and cannot act on the client’s behalf. You learn what the client does from the events. For a client who called you, use the client added by hand.
• Messages to people: confirmations, reminders and the day’s agenda are sent by the app, also when the action comes through the API.
• The printable open house poster. The API gives you the link to the sheet at the door, and you draw the QR code yourself.

The agenda

{
  "data": {
    "code": "HEWPUTA8",
    "duration_min": 30,
    "confirmation": "manual",
    "slots": [
      { "id": 9182, "kind": "viewing", "starts_at": "2026-11-12T10:00:00+00:00", "ends_at": "2026-11-12T10:30:00+00:00",
        "status": "pending", "request_expires_at": "2026-11-11T09:14:00+00:00",
        "visitor": { "name": "Ana Popescu", "email": "ana@example.com", "phone": "+40740123456" } },
      { "id": 9190, "kind": "open_house", "starts_at": "2026-11-15T08:00:00+00:00", "ends_at": "2026-11-15T12:00:00+00:00",
        "status": "available", "request_expires_at": null, "visitor": null }
    ]
  }
}

• kind is viewing (a time one visitor books) or open_house (an open house window, with no booking).
• status is available (free), pending (requested by a visitor, waiting for your answer) or booked.
• request_expires_at is when you have to answer a request by. After it, the request expires and the time is free again.
• visitor has the name, email and phone of the person who booked or requested the time. Only a key with the leads:read permission gets it, since it is the same data as a client request. For other keys it is null. A booking also brings a new request, with source: viewing_request.

Settings

{ "duration_min": 45, "confirmation": "auto" }

• duration_min is how long a viewing lasts, in minutes: 15, 30, 45, 60 or 90. Times already published keep their length.
• confirmation is auto (a booking is confirmed at once) or manual (the visitor sends a request, and you accept or decline it).

Viewing times and open house days

{ "slots": ["2026-11-12T10:00", "2026-11-12T10:30", "2026-11-12T11:00"], "duration_min": 30 }

{ "windows": [ { "starts_at": "2026-11-15T10:00", "ends_at": "2026-11-15T14:00" } ] }

• A time without a time zone (2026-11-12T10:00) is read on the clock of the listing’s location, as the visitor sees it. You can also send a moment with an offset (2026-11-12T08:00:00Z). A time that does not exist, or happens twice when the clocks change, is refused.
• Times must be in the future, and a window ends after it starts.
• Viewing times do not overlap each other or an open house window. A time already published is skipped, so the same list sent twice adds nothing.
• A duration_min sent when publishing becomes the listing’s duration. With "set_listing_duration": false, the times are published with their own duration and the listing’s stays as it was.
• The agenda changes only on an active listing. On any other listing the response is 409 listing_action_refused.

Requests and bookings

• POST /viewings/{id}/accept accepts a request: the time becomes booked, and the visitor gets the confirmation.
• POST /viewings/{id}/decline declines a request: the time is free again, and the visitor learns the request was declined.
• POST /viewings/{id}/cancel cancels a booking or a request: the time stays published and free, and the visitor is told. With note (at most 300 characters), the note goes into the message to them, if they have an account.

Events

• viewing.booked: a visitor booked or requested a viewing time. data has slot_id, starts_at and slot_status (booked or pending).
• viewing.cancelled: a booking or a request was cancelled without you. data has slot_id, starts_at and by: visitor when the visitor cancelled, expired when the request expired without an answer.