# Activity and viewings

> Register viewings on your listings, name the outside agent who sent the client, and read a listing's activity feed.

Record viewings on your own listings and read everything that happened to a listing (viewings, changes, deal moves and brochures) as one feed.

These routes take a signed-in dashboard session with an active organization (`Authorization: Bearer <session token>`); a property API key is refused. To read viewings with a key, use `GET /integrations/v1/viewings` (see [Integrations API](https://www.fondaro.com/docs/api/integrations.md)). A listing outside your organization returns `404`.

Any member can read and register viewings. A member can change or delete only viewings they created; an admin can change any.

## List viewings

### `GET /properties/:id/viewings`

| Query | Default | Range |
|---|---|---|
| `limit` | 20 | 1 to 100 |
| `offset` | 0 | 0 or more |

```bash
curl "https://api.fondaro.com/properties/29a1e184-237a-40c8-a1fe-624b0bcbb2f4/viewings?limit=20" \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

```json
{
  "viewings": [
    {
      "id": "67444de5-bfa4-4aa4-87c3-a1b2f1a4af59",
      "propertyListingId": "29a1e184-237a-40c8-a1fe-624b0bcbb2f4",
      "leadId": 4312,
      "otherLeadIds": [4318],
      "collaboratorLeadId": null,
      "agentUserId": "user_2abc123",
      "dealId": null,
      "viewingAt": "2026-10-08T09:30:00.000Z",
      "kind": "in_person",
      "status": "scheduled",
      "notes": "Meet at reception.",
      "source": "user",
      "createdBy": "user_2abc123"
    }
  ],
  "total": 1,
  "hasMore": false
}
```

Newest `viewingAt` first. `kind` is `in_person` or `virtual`; `status` is `scheduled`, `completed`, `cancelled` or `no_show`. Deleting a linked lead or deal clears the link, never the viewing.

## Register a viewing

### `POST /properties/:id/viewings`

| Field | Type | Rules |
|---|---|---|
| `viewingAt` | ISO 8601 | Required |
| `kind` | string | Required: `in_person` or `virtual` |
| `status` | string | Optional; omitted, a past time becomes `completed` and a future one `scheduled` |
| `leadId` | integer | The client, a lead you can see |
| `otherLeadIds` | integer[] | Other clients on the same viewing, leads you can see; up to 19 |
| `collaboratorLeadId` | integer | An outside agent kept as a lead in your CRM |
| `agentUserId` | string | Who hosts; defaults to you |
| `dealId` | UUID | A deal in your organization |
| `notes` | string | Up to 5,000 characters |

```bash
curl -X POST https://api.fondaro.com/properties/29a1e184-237a-40c8-a1fe-624b0bcbb2f4/viewings \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"viewingAt":"2026-10-08T09:30:00Z","kind":"in_person","leadId":4312}'
```

Returns the created viewing. A member may link only leads assigned to them; an admin may link any lead in the organization. Linking a lead grants no access to it.

## Change or delete a viewing

### `PATCH /viewings/:viewingId`

Takes the create fields, all optional. A key you leave out is unchanged; `otherLeadIds` replaces the other clients, and `[]` removes them; `null` clears `leadId`, `collaboratorLeadId`, `agentUserId`, `dealId` or `notes`. A new `viewingAt` does not recalculate `status`: send it too.

```bash
curl -X PATCH https://api.fondaro.com/viewings/67444de5-bfa4-4aa4-87c3-a1b2f1a4af59 \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed","notes":"Wants a second visit."}'
```

### `DELETE /viewings/:viewingId`

```json
{ "success": true }
```

## Read activity

### `GET /properties/:id/activity`

One feed of a listing's viewings, changes, deal events and brochures, newest first.

| Query | Default | Meaning |
|---|---|---|
| `types` | all | `viewing`, `change`, `deal`, `brochure`; comma-separated or repeated |
| `limit` | 20 | 1 to 100 |
| `offset` | 0 | 0 or more |

```bash
curl "https://api.fondaro.com/properties/29a1e184-237a-40c8-a1fe-624b0bcbb2f4/activity?types=viewing,deal" \
  -H "Authorization: Bearer $SESSION_TOKEN"
```

```json
{
  "entries": [
    {
      "type": "viewing",
      "date": "2026-10-08T09:30:00.000Z",
      "viewing": { "id": "67444de5-bfa4-4aa4-87c3-a1b2f1a4af59", "kind": "in_person", "status": "scheduled" },
      "lead": { "id": 4312, "firstName": "Alex", "lastName": "Morgan" },
      "collaborator": null
    }
  ],
  "total": 1,
  "hasMore": false
}
```

Entry types: `viewing` (with `lead` and `collaborator` names), `change` (a [history event](https://www.fondaro.com/docs/api/properties/own-listings.md#history)), `deal-stage-change`, `deal-won` and `deal-lost` (all under the `deal` filter), and `brochure`. Page with `hasMore` and `offset`; `total` can be a lower bound for long histories.

## Errors

| Status | When |
|---|---|
| `400` | An invalid value |
| `401` | A property API key, or no session |
| `403` | Linking a lead you cannot see, or changing another member's viewing |
| `404` | The listing, viewing, lead or deal is not in your organization |

Source: https://www.fondaro.com/docs/api/properties/activity