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

# Viewings

> What you can do with viewings through the API, from the weekly schedule to the owner's report, with which permissions, and what stays in the app only.

On a published listing you can offer viewing times, which visitors book from the listing page, and open house days, when anyone can come without booking. Through the API you do everything the person who publishes the listing does in the app, under the same rules: the hours, the agenda, the open house, the attendance sheet, the reports and the viewings on a project. The basic operations on a listing's agenda are described below, and the rest in the guides in the table.

## What you can do through the API

| In the app | Through the API | Guide |
| - | - | - |
| “My schedule” and each listing's schedule | `GET`/`PATCH /account/viewing-schedule`, `GET /account/listings/{code}/viewing-schedule`, `PATCH /listings/{code}/viewing-schedule`, `POST /account/viewing-schedule/apply` | [Weekly schedule](https://api.housera.ro/en/guides/viewing-schedule.md) |
| The agenda across all listings and a viewing's sheet | `GET /account/viewings`, `GET /viewings/{id}` | [Viewing agenda](https://api.housera.ro/en/guides/viewing-agenda.md) |
| A listing's agenda: hours, windows, requests, bookings | `GET /account/listings/{code}/viewings` and the operations below | this page |
| The client who called, another hour, cancelling with a note, “How did it go?” | `POST /listings/{code}/viewings/clients`, `POST /viewings/{id}/proposal`, `POST /viewings/{id}/cancel`, `PUT /viewings/{id}/outcome` | [Viewing agenda](https://api.housera.ro/en/guides/viewing-agenda.md) |
| An open house with a note, sign-up and places, telling the people who saved the listing | `POST /listings/{code}/open-house`, `PATCH /viewings/{id}/open-house`, `POST /viewings/{id}/open-house/announce` | [Open house](https://api.housera.ro/en/guides/open-house.md) |
| The attendance sheet | `GET`/`POST /viewings/{id}/attendees` and the operations on `/open-house-attendees/{id}` | [The attendance sheet](https://api.housera.ro/en/guides/open-house.md#the-attendance-sheet) |
| The listing's report and the owner's link | `GET /account/listings/{code}/viewing-report`, `POST`/`DELETE /listings/{code}/viewing-report/link`, `POST /listings/{code}/viewing-report/send` | [Viewing reports](https://api.housera.ro/en/guides/viewing-reports.md) |
| Viewings on a developer's projects | the `viewings` field on a project, `POST /projects/{code}/flat-viewings`, `GET /account/projects/{code}/viewing-report` | [Viewings on a project](https://api.housera.ro/en/guides/projects.md#viewings-on-a-project) |
| What happens without you (a client books, confirms, answers another hour) | the `viewing.*` and `open_house.attendee_*` events | [Viewing events](https://api.housera.ro/en/webhooks.md#viewing-events) |

## 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

Data read through the API has the same terms as in the app. The name and phone of a client added by hand are removed from the viewing after 90 days. The rows of an attendance sheet are deleted 90 days after the open house, and the window stays. The answer to “How did it go?” and its note are deleted after 24 months. An owner's link works for 90 days at most. The contact you keep in the requests has its own term. If you keep this data in your system, delete it on the same terms.

## 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](https://api.housera.ro/en/guides/viewing-agenda.md#the-client-who-called).
* 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

`GET /account/listings/{code}/viewings` returns the settings, plus the viewing times and open house windows that have not passed yet:

```json theme={null}
{
  "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](https://api.housera.ro/en/guides/leads.md). For other keys it is `null`. A booking also brings a new request, with `source: viewing_request`.

Each hour also has fields that say where it comes from and what happened to it (`source`, `bookable`, `outcome`, `agent`, `open_house` and others). They are described in [Viewing agenda](https://api.housera.ro/en/guides/viewing-agenda.md). On this endpoint `status` stays `available`, `pending` or `booked`, and an hour that has passed no longer appears.

Every change below answers with the updated agenda, in the same shape.

## Settings

`PATCH /listings/{code}/viewings` changes one or both settings:

```json theme={null}
{ "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

`POST /listings/{code}/viewings` publishes viewing times, at most 400 in one request:

```json theme={null}
{ "slots": ["2026-11-12T10:00", "2026-11-12T10:30", "2026-11-12T11:00"], "duration_min": 30 }
```

`POST /listings/{code}/open-house` publishes open house windows, at most 60 in one request:

```json theme={null}
{ "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`.

`PATCH /viewings/{id}` moves a viewing time or a window (`starts_at`, plus `ends_at` for a window). A time booked by a client with an account is not moved: you propose another time ([Viewing agenda](https://api.housera.ro/en/guides/viewing-agenda.md#another-hour-for-a-client-with-an-account)), cancel it or answer the request. The viewing of a client without an account, added by hand, is moved directly, since you agreed the new time together.

`DELETE /viewings/{id}` withdraws a time or a window (`204`). If the time was booked or requested, the visitor is told. `POST /listings/{code}/viewings/withdraw` with `{"slot_ids": [9182, 9183]}` withdraws several free times at once. Booked or requested times stay, and you withdraw them one by one.

## 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.

A request that was already answered gets `409 listing_action_refused`. A time on a listing the key cannot see answers `404`.

A developer's consultant answers the bookings that came to them on a project the same way. The answer is the listing's agenda with the times they see in the app: their clients and the open house days. The whole agenda (`GET /account/listings/{code}/viewings`), moving times and withdrawing them stay with whoever runs the listing's viewings. The consultant finds their times in `GET /account/viewings`.

## 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.

You get them like the listing's other events, with the `listings:read` permission. From the day we announce to you, you also get the events for what your colleague does in the app (confirms, declines, cancels, moves, proposes another hour, says how it went) and for the attendance sheet. See [Viewing events](https://api.housera.ro/en/webhooks.md#viewing-events).


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