# Viewings and open houses

> List and read the viewings of your own listings and the open houses on the Fondaro network through the Fondaro API.

These routes are reads and need `properties:read`. They are open to members and admins alike, and none needs an active plan. A viewing or open house you cannot reach answers `404` with `NOT_FOUND`, the same as one that does not exist.

## List viewings

`GET /v1/viewings`

Registered viewings of your agency's own listings, latest viewing time first. Filters combine. Notes are previews of up to 500 characters (`notesTruncated` says when one was cut); read one viewing for the full text.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `limit` | Query | integer | No | 1 to 100. Default 20 |
| `offset` | Query | integer | No | Rows to skip. Continue with `nextOffset` |
| `from` | Query | string | No | ISO 8601 date-time. Viewings at or after it (inclusive) |
| `to` | Query | string | No | ISO 8601 date-time. Viewings before it (exclusive) |
| `status` | Query | string | No | `scheduled`, `completed`, `cancelled` or `no_show` |
| `kind` | Query | string | No | `in_person` or `virtual` |
| `propertyListingId` | Query | UUID | No | Only viewings of this own listing |
| `leadId` | Query | integer | No | Only viewings for this lead |
| `collaboratorLeadId` | Query | integer | No | Only viewings for this collaborating agency's lead |
| `dealId` | Query | UUID | No | Only viewings of this deal |
| `agentUserId` | Query | string | No | Only viewings held by this agent |

```bash
curl "https://api.fondaro.com/v1/viewings?limit=2" \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

```json
{
  "data": [
    {
      "id": "3f6c2a10-0000-4000-8000-000000000013",
      "propertyListingId": "3f6c2a10-0000-4000-8000-000000000012",
      "leadId": null,
      "collaboratorLeadId": null,
      "agentUserId": "user_2abcDEF1234567890ghiJKL",
      "dealId": null,
      "viewingAt": "2026-09-29T09:30:00.000Z",
      "kind": "in_person",
      "status": "cancelled",
      "source": "user",
      "createdBy": "user_2abcDEF1234567890ghiJKL",
      "createdAt": "2026-09-29T09:20:06.646Z",
      "updatedAt": "2026-09-29T09:20:36.632Z",
      "notes": null,
      "notesTruncated": false
    }
  ]
}
```

The response also carries `hasMore`, `nextOffset` while there is more, and an exact `total`. Paging is by offset. Errors: `400` for a bad filter value.

## Get a viewing

`GET /v1/viewings/{viewingId}`

One viewing of your agency by id, with its full notes. A lead id on it does not give you access to that lead.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `viewingId` | Path | UUID | Yes | The id of the viewing |

```bash
curl https://api.fondaro.com/v1/viewings/3f6c2a10-0000-4000-8000-000000000013 \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

The response is the viewing, in the shape shown above. Errors: `404` `NOT_FOUND`.

## List open houses

`GET /v1/open-houses`

Open houses in one of two scopes: `network` (the default), the upcoming events other agencies opened to the Fondaro network, nearest first; or `mine`, your own agency's events in any status. Each row has the time window, the host agency, the commission offered to collaborating agents, how many agents are going, your own RSVP and a summary of the listing.

There is no paging. Narrow with `from`, `to`, `area` or one exact listing, up to 25 rows; `hasMore` says when more matched.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `scope` | Query | string | No | `network` (default) or `mine` |
| `from` | Query | string | No | ISO 8601 date-time. Events ending after it. Default now |
| `to` | Query | string | No | ISO 8601 date-time. Events starting before it |
| `area` | Query | string | No | City, area or community of the listing |
| `source` | Query | string | No | Only events whose listing comes from this source |
| `listingSource`, `listingId` | Query | string | No | Both together: ask about one listing exactly |
| `listingCountry` | Query | string | No | The listing reference's country, when it has one |
| `limit` | Query | integer | No | 1 to 25. Default 10 |

```bash
curl "https://api.fondaro.com/v1/open-houses?limit=2" \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

```json
{ "data": [], "hasMore": false }
```

A row carries `id`, `status`, `visibility`, `startsAt`, `endsAt`, `timezone`, `host`, `isHost`, `commissionOffer`, `commissionNotes`, `goingCount`, `myRsvp`, `listingRef` and a `listing` summary (title, reference number, type, city, area, price, currency, bedrooms, bathrooms and main image).

## Get an open house

`GET /v1/open-houses/{openHouseId}`

One open house by id: the window, the host agency, the disclosed address, the commission offered, the invitation, the event contact and the listing. The listing owner's private commission is never included.

| Parameter | In | Type | Required | Description |
|-----------|----|------|----------|-------------|
| `openHouseId` | Path | UUID | Yes | The id of the open house |

```bash
curl https://api.fondaro.com/v1/open-houses/9d1f3a52-6b7e-4c0a-8f21-3e5b7a9c1d04 \
  -H "Authorization: Bearer $FONDARO_API_KEY"
```

The response has the fields of a list row plus `slug`, `disclosedAddress`, `mapUrl`, `contactName`, `contactPhone`, `hostUserId` and `invitation`. Errors: `404` `NOT_FOUND`.

Source: https://www.fondaro.com/docs/api/v1/viewings-and-open-houses