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

# Leases

> Lease status fields, lease type, subleases, and the spaces a lease occupies

A **lease** is an agreement between a landlord and a tenant for space in a building. It is the anchor for everything Prophia extracts: its [documents](https://docs.prophia.com/api-reference/v2/concepts/documents.md) are what get processed, and its [tags](https://docs.prophia.com/api-reference/v2/concepts/tags-and-values.md) are what comes out.

## Three status fields, three questions

A lease carries three status-like fields. They answer different questions — read the one that matches yours:

| Field | Question it answers | Values |
| - | - | - |
| `leaseStatus` | Is this lease active? | One of `Active`, `Expired`, or `Not Started` — note the spacing and casing. Typed as a free-form string, so don't switch on it exhaustively. |
| `leaseSubStatus` | *How* is it currently running? | `{status, startDate}` where status is `MONTH_TO_MONTH`, `YEAR_TO_YEAR`, `HOLDOVER`, `VACATED`, or `EXTENDED`. **Omitted entirely when none applies** — most leases in their original term have no sub-status. |
| `docCompletionStatus` | Has Prophia finished curating this lease's data? | `complete` when every document on the lease has `documentStatus: complete` exactly, otherwise `incomplete`. [Account-specific review states](https://docs.prophia.com/api-reference/v2/concepts/documents.md#documentstatus-the-curation-lifecycle) count as not complete. |

### `leaseStatus` is derived, and the sub-status can override the dates

`leaseStatus` is computed per request, not stored. Prophia resolves it in this order:

1. **Is the lease holding over?** If its sub-status is `HOLDOVER`, `MONTH_TO_MONTH`, or `YEAR_TO_YEAR`, it is **`Active`** — full stop. This check runs before any date comparison.
2. **Otherwise, is it expired?** `Expired` when `expirationDate` is in the past, or when the sub-status is `VACATED` — which forces `Expired` even on a future expiration date.
3. **Otherwise, has it commenced?** `Not Started` when `commenceDate` is absent or still in the future.
4. **Otherwise** — `Active`.

`EXTENDED` is the one sub-status that doesn't steer the outcome; it annotates a lease whose status still follows its dates.

> [!WARNING]
>
> **An `expirationDate` in the past does not mean `leaseStatus` is `Expired`.** A tenant still in place month-to-month past the end of the original term reads `leaseStatus: "Active"` with `leaseSubStatus: {status: "MONTH_TO_MONTH"}`. Read `leaseStatus`; don't recompute expiry from `expirationDate` yourself, or you will report occupied space as vacant.

> [!WARNING]
>
> `docCompletionStatus` is about **data curation, not availability**. A lease's tags are readable long before curation finishes, but until it reads `complete` Prophia's team has not signed off on them and values can still change. Treat `incomplete` leases as provisional. See [Understanding onboarding](https://docs.prophia.com/api-reference/v2/concepts/onboarding.md) for the whole arc.

## Lease type shapes what you see

`leaseType` is more than a label — it filters which extracted terms surface on the lease. Prophia keeps type-specific term sets, and a term belonging to one type only appears on leases of that type. `RETAIL` and `GSA_OFFICE` each carry tags no other type does; see the [tag reference](https://docs.prophia.com/api-reference/v2/concepts/tag-reference.md#lease-type-and-country-scoping) for which ones.

> [!WARNING]
>
> Changing a lease's `leaseType` changes its tag list. Switch a `GSA_OFFICE` lease to `OFFICE` and its GSA-only terms stop appearing in the consolidated tags — the tags still exist on the documents, but they no longer match the lease's type. Treat a `leaseType` change as a change to the lease's data shape, not just its classification.

Types: `OFFICE` (the default when omitted on create), `GSA_OFFICE`, `RETAIL`, `INDUSTRIAL`, `STORAGE`, `LICENSE_AGREEMENT`, `TELECOM_ANTENNA`, `PARKING_AGREEMENT`, `ROOFTOP_SOLAR`.

## Where a lease sits: `suiteNumber`

`Lease.suiteNumber` is a **list** of space objects `{name, buildingId, scope}` — every space the lease occupies:

```json theme={null}
"suiteNumber": [
  { "name": "Suite 300", "buildingId": "bld_456", "scope": "SUITE" },
  { "name": "Suite 400", "buildingId": "bld_456", "scope": "SUITE" }
]
```

An entry's `buildingId` can differ from the lease's own `buildingId` when the lease spans multiple buildings or has relocated. The lease's `buildingId` records where the lease was filed, not necessarily every building it now occupies.

`leasedFloors` is derived from this list rather than captured: each entry is matched to a building space and contributes that space's `floor`. It inherits the same [name-matching caveats](https://docs.prophia.com/api-reference/v2/concepts/spaces-and-encumbrances.md#the-soft-link-to-buildingspace).

## Subleases

A sublease is a **full lease object**, not a separate type:

* `parent` is present **if and only if** the lease is a sublease — a lightweight ref (`id`, `url`, and the parent's current `leaseStatus`/`leaseSubStatus` when available).
* `subleases` lists the lease's subleases as the same lightweight refs, and is only populated when you request [`include=subleases`](https://docs.prophia.com/api-reference/v2/concepts/includes). An empty list means the lease has none.

Both are refs rather than full objects, so fetch a sublease by id to read its own terms.

## Rent classification

`rentType` is the headline classification for the lease — `Gross`, `Modified Gross`, `Single Net`, `NN`, `NNN`, `Net`, `Net of E`, or `Unknown`. `opexTaxTypes` refines it per occupied space, falling back to `rentType` where no per-space mapping exists. A lease whose spaces are all on the same terms will simply repeat the headline value.

## Reading a lease's terms

The lease's extracted terms arrive through [`include=tags`](https://docs.prophia.com/api-reference/v2/concepts/includes) or the dedicated [`GET .../leases/{leaseId}/tags`](https://docs.prophia.com/api-reference/v2/leases/list-tag) endpoint. Beyond the `leaseType` filtering above, one thing to know before you parse them: the list is a **consolidated** view assembled across the lease's whole document history, flattened from a per-space map. The same `tagName` can appear more than once — once per space — with different values. See [Tags and tag values](https://docs.prophia.com/api-reference/v2/concepts/tags-and-values.md#space-dependent-and-space-independent-tags).


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