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

# Documents

> Uploading documents, the documentStatus lifecycle, categories, and change detection

A **document** (`LeaseDoc`) is a file attached to a lease — the original lease agreement, an amendment, a work letter, an exhibit. Documents are the raw material for everything Prophia extracts: [tags](https://docs.prophia.com/api-reference/v2/concepts/tags-and-values.md) come from documents, and a lease's data is only as complete as its documents are.

A filename cannot be duplicated within a single lease. Documents can also be filed against a **property** or a **building** rather than a lease — rent rolls, stacking plans — and those are reached with [`include=documents`](https://docs.prophia.com/api-reference/v2/concepts/includes) on the property or building.

## `documentStatus`: the curation lifecycle

`documentStatus` reports how far a document has moved through Prophia's pipeline and review. It is not a simple binary, and the last step is a human one.

A document normally travels:

```
processing  →  incomplete  →  [account-specific review states]  →  complete
```

| Value | What it means |
| - | - |
| `processing` | The document is in Prophia's AI ingestion pipeline. The pipeline's internal states — text extraction, indexing, prediction — are deliberately collapsed to this one value. Pages and tags aren't final yet. |
| `incomplete` | The AI pipeline has finished. The document has been read and machine-tagged, and it is now **ready for human review**. This is where every document lands when it leaves the pipeline. Data is readable but not signed off. |
| *account-specific values* | Review states configured on your account by Prophia's operations team, used to track where a document sits in the curation workflow. An account with none configured goes straight from `incomplete` to `complete`. |
| `complete` | The document's data has been **fully curated** — Prophia's team has reviewed and finished it. This is the only value that means the extracted data is final. |

> [!NOTE]
>
> That order is the normal path, not an enforced state machine. A reviewer can move a document to any state at any point, so don't build a client that assumes it will observe each step, or that a document only ever moves forward.
>
> The one guarantee to lean on: **`documentStatus === "complete"` is the whole test for curated.** Account-specific status names are validated against the built-in set when they're created, so a custom state can never be named `complete` or `incomplete` — which means any value you don't recognize is a review state that hasn't reached the end yet. (If an account-specific status is later deleted, documents sitting on it fall back to `incomplete`.)

`documentStatus` is typed as a plain string rather than an enum for exactly this reason — the account-specific values are open-ended. `processing` is also the only value that means "not readable yet"; everything after it is readable, and the question is just how much of it has been reviewed. If you are mirroring Prophia data, `complete` is the line to gate on.

A lease rolls this up into [`docCompletionStatus`](https://docs.prophia.com/api-reference/v2/concepts/leases#three-status-fields-three-questions), which applies exactly that test: `complete` only when *every* document on the lease is `complete`, and `incomplete` when any one of them sits on anything else — a built-in state or an account-specific one. A building rolls the leases up in turn — see [Understanding onboarding](https://docs.prophia.com/api-reference/v2/concepts/onboarding.md).

## Uploading a document

**1. Upload**

[`POST /rest/v2/accounts/{accountId}/docs/upload`](https://docs.prophia.com/api-reference/v2/documents/create-document-via-upload) — a multipart form with `file` and `leaseId` required, plus optional `filename`, `title`, and `docCategory`. Or [`POST .../docs`](https://docs.prophia.com/api-reference/v2/documents/create-document-via-url) to have Prophia fetch it from a presigned https URL instead.

**2. Poll**

Re-fetch the lease's documents with [`GET .../leases/{leaseId}/docs`](https://docs.prophia.com/api-reference/v2/leases/list-document) on a modest interval — pipeline processing takes minutes, so start around 30–60 seconds — until the new document's `documentStatus` is no longer `processing`.

**3. Read**

Once it clears, page geometry ([`GET .../docs/{leaseDocId}/pages`](https://docs.prophia.com/api-reference/v2/documents/list-page)) and extracted tags ([`GET .../docs/{leaseDocId}/tags`](https://docs.prophia.com/api-reference/v2/documents/list-tag)) are available. Remember they are machine-extracted until the document reaches `complete`.

Both create endpoints require [write access](https://docs.prophia.com/developers/write-access.md).

> [!WARNING]
>
> Only PDFs are processed, and the test is the **filename**, not the file's contents. Both create endpoints accept any file type up to 200 MB, but a document whose name doesn't end in `.pdf` is stored and attached as-is: it settles at `documentStatus: "complete"` without a processing pass, and never has pages or tags. Name a PDF something else and it won't be read; name a non-PDF `.pdf` and ingestion will try, then fail.

## `docCategory`

`docCategory` classifies the document — `Main Lease Agreement`, `Extension - Amendment`, `Rent Roll`, `Work Letter`, and so on. It is filterable on the document list endpoints and it is not cosmetic: some categories determine which tags and in-app features a document participates in.

Leave it blank on create and Prophia's AI will inspect the document and set it, with human review to follow. The AI will **not** overwrite a category you set yourself, so supply one when you already know it.

## Citations

A tag's provenance lives on the document. Request [`include=tagSelections,pages`](https://docs.prophia.com/api-reference/v2/concepts/includes) on any tag endpoint and you get the rectangles where each value was captured, plus the geometry of the pages they sit on. See [Tags and tag values](https://docs.prophia.com/api-reference/v2/concepts/tags-and-values.md#citations-tagselections-and-pages) for the coordinate system.

## Change detection for sync jobs

If you mirror Prophia data into a warehouse, don't re-crawl the whole tree. [`GET /rest/v2/accounts/{accountId}/recent_changed_leases`](https://docs.prophia.com/api-reference/v2/accounts/list-leases-recently-updated) returns leases whose **documents** changed inside a `start_date`–`end_date` window (inclusive, `yyyy-MM-dd`) — poll it and re-fetch only what it names. It accepts the same [`include`](https://docs.prophia.com/api-reference/v2/concepts/includes) keys as other lease reads (`tags`, `documents`, `subleases`).

Because the window is keyed on document change, this catches the events that matter most for a mirror: a new amendment landing, and a document moving to `complete` as curation finishes.


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