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

# Includes

> Embed related resources in one request with the include query parameter

Most read endpoints accept an `include=` query parameter that embeds related collections in the response, saving you a round trip per relationship. Keys are comma-separated:

```bash theme={null}
curl "https://api.prophia.com/rest/v2/accounts/{accountId}/leases/{leaseId}?include=tags,subleases" \
  -H "X-API-Key: <your-api-key>"
```

## Before and after

Without `include`, a property is just its own fields:

```json theme={null}
{
  "id": "prop_123",
  "propertyName": "Waterfront Plaza",
  "customId": "WFP-01"
}
```

With `?include=buildings`, the related collection is embedded:

```json theme={null}
{
  "id": "prop_123",
  "propertyName": "Waterfront Plaza",
  "customId": "WFP-01",
  "buildings": [
    { "id": "bld_456", "buildingName": "Waterfront Plaza — North Tower" },
    { "id": "bld_789", "buildingName": "Waterfront Plaza — South Tower" }
  ]
}
```

## The rules

* **One level deep, strictly.** There is no `include=buildings.leases` — includes never chain. Walk the tree with successive requests instead: list buildings, then request each building with `include=leases`.
* **Unknown keys are rejected with `400`.** Misspell a key and the error message lists every key the endpoint supports. This is deliberately stricter than `sortBy`, which [silently falls back](https://docs.prophia.com/api-reference/v2/concepts/pagination-and-filtering.md) — don't assume the two behave alike.
* **Each key can require an extra capability.** Your key needs the read capability for the *embedded* resource as well as the primary one — for example, `GET /leases/{leaseId}?include=tags` requires tag read on top of lease read. A request missing a capability is **rejected with `403`**, not silently trimmed. See [Errors and permissions](https://docs.prophia.com/api-reference/v2/concepts/errors-and-permissions.md).
* **Absent ≠ empty.** Responses omit fields that are `null`, so an include you didn't request is missing from the JSON entirely. An empty array means you asked and there were none — [branch on presence](https://docs.prophia.com/api-reference/v2/concepts/data-model.md#absent-means-not-requested).

## Supported keys by endpoint

| Endpoint | Keys | Extra capability per key |
| - | - | - |
| `GET /accounts`, `GET /accounts/{accountId}` | `properties` | property read |
| `GET .../recent_changed_leases` | `tags`, `documents`, `subleases` | tag read / document read / — |
| `GET .../properties`, `GET .../properties/{propertyId}` | `buildings`, `documents` | building read / document read |
| `GET .../properties/{propertyId}/buildings` | `leases`, `documents`, `spaces` | lease read / document read / building-space read |
| `GET .../properties/{propertyId}/leases` | `tags`, `documents`, `subleases` | tag read / document read / — |
| `GET .../buildings`, `GET .../buildings/{buildingId}` | `leases`, `documents`, `spaces` | lease read / document read / building-space read |
| `GET .../buildings/{buildingId}/leases` | `tags`, `documents`, `subleases` | tag read / document read / — |
| `GET .../leases/{leaseId}` | `tags`, `documents`, `subleases` | tag read / document read / — |
| `GET .../leases/{leaseId}/tags` | `tagSelections`, `pages`, `applicableSpaces` | — (covered by tag read) |
| `GET .../docs/{leaseDocId}/tags` | `tagSelections`, `pages`, `applicableSpaces` | — (covered by tag read) |
| `GET .../tags/{tagId}` | `tagSelections`, `pages`, `applicableSpaces` | — (covered by tag read) |

Endpoints not in this table don't take `include`: the document list (`GET .../leases/{leaseId}/docs`), document pages, building spaces, and custom terms.

## What the keys mean

* `properties` / `buildings` / `leases` — the flat child list under the resource, limited to what your key is permitted to see.
* `spaces` — the building's spaces, **archived and non-archived alike**. The dedicated [spaces endpoint](https://docs.prophia.com/api-reference/v2/concepts/spaces-and-encumbrances.md#building-spaces) takes an `archived` filter; this key does not.
* `documents` — on properties and buildings: documents filed at that scope (rent rolls, stacking plans). On leases: per-document page geometry keyed by `leaseDocId`, for resolving a tag's `tagSelections[].docPageId` references.
* `tags` — the consolidated [DocTag list](https://docs.prophia.com/api-reference/v2/concepts/tags-and-values.md) assembled from the lease's documents, filtered by the lease's current `leaseType`. Each tag carries only the spaces it applies to; see [space-dependent and space-independent tags](https://docs.prophia.com/api-reference/v2/concepts/tags-and-values.md#space-dependent-and-space-independent-tags).
* `subleases` — lightweight refs (`id`, `url`, current `leaseStatus`/`leaseSubStatus`) to the lease's subleases; an empty list means the lease has none.
* `tagSelections` — the tag's citations: bounding boxes on document pages.
* `pages` — per-page geometry for the cited pages.
* `applicableSpaces` — the suite/floor list the tag applies to. See [Spaces and encumbrances](https://docs.prophia.com/api-reference/v2/concepts/spaces-and-encumbrances.md).

> [!WARNING]
>
> Combining `tags` and `documents` on a heavily-tagged lease can produce a very large response. Request one at a time when you can.


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