Skip to main content
A tag (DocTag) is one extracted lease term — a rent amount, a renewal option, a commencement date — anchored to the exact place in a document it came from. Tags are the payoff of Prophia’s document processing: ask a lease for its tags and you get the abstracted deal terms with citations.
For the complete list of terms Prophia captures — every tagName, the units it can carry, and what its customValue fields hold — see the tag reference.

Three unrelated “custom” things

Three features share the word custom. They have nothing to do with each other:

Categories

category tells you how much structure to expect:

Typed values: branch on kind

value is polymorphic. Every shape carries a kind discriminator plus the common fields unit, capturedData (the value as captured, as text) and ocrText (the raw source text). Empty fields are omitted.
Money values are decimal strings, not JSON numbers — "value": "120000.00" — to preserve cent precision. Parse them as decimals, never as floats.
kind alone is not enough — always read unit too. A single number covers durations, areas and plain counts, and only unit separates them. And because the kind follows the captured unit rather than the term, the same tagName can hand you money on one lease and percent or text on another: rentBump and opexCap accept both dollar and percent units, and a rental rate captured as FMV or landlordDefined comes back as text.A percent value carries the percentage itself, so 3.5 means three and a half percent.
Typed fields are best-effort. They are populated by parsing capturedData, so a typed field is omitted when the captured text couldn’t be parsed into that kind — common for dates a lease states in relative terms (“ninety days after substantial completion”). capturedData always holds the raw text, and it is the fallback whenever a typed field is missing.
value is the percentage itself — six percent, not 0.06.
Stored as free text, so it arrives as text despite sitting on a field you might expect to be money.
No value — only capturedData.

Space-dependent and space-independent tags

Every term is defined as either space-dependent or space-independent, and this decides how the lease’s tag list is assembled.
  • Space-dependent terms are consolidated per space. Square footage, rent schedules, renewals, early terminations — each space the lease occupies can carry its own value. In the flattened list you get back, the same tagName can therefore appear more than once, once per space, with different values and different applicableSpaces.
  • Space-independent terms are consolidated per term name, one value for the whole lease. Tenant legal name, effective date, exclusive use, permitted use.
In a lease’s consolidated tags (include=tags on a lease), each tag appears once, with the spaces it wins in the consolidation:
  • A space-independent tag has no applicableSpaces. It applies to the lease, not to a particular suite.
  • A space-dependent tag lists the spaces it applies to. A term captured without any spaces applies to every space, so it lists all of them.
  • Rent schedules, and the monthly and annual rents derived from them, can be consolidated differently per space. When that happens the same tag id appears once per space group, each copy with its own values and applicableSpaces.
Lease-level values that summarize every space, such as the lease’s commencement and expiration dates and its total square footage, are on the lease’s top-level fields (commenceDate, expirationDate, squareFootage, suiteNumber), not in tags.
Keying a client-side map on tagName alone will silently drop values for a multi-space lease. Key on tagName + applicableSpaces for space-dependent terms. The tag reference marks which terms are which.
Request include=applicableSpaces to see which spaces a tag applies to. See Spaces and encumbrances for how those entries match your space inventory.

customValue1–customValue6: positional and tag-dependent

These six string fields mean different things on different tags — the position, not the name, carries the meaning. Some encode a whole multi-period schedule as :-:-delimited parallel arrays.
Never interpret a customValue without knowing which tagName it belongs to. Treat undocumented combinations as opaque — they are not guaranteed to mean anything.

Schedules

Tags whose value is a series carry a schedule of {kind, entries}. Branch on kind, which determines the entry shape: RENT, PERCENT_RENT, ABATEMENT, REFUND, or FEE. Every entry has a 0-indexed sequence, and every entry except REFUND is bounded either by calendar dates (startDate/endDate) or by 1-indexed months from lease commencement (startMonth/endMonth, where month 1 is the commencement month) — whichever way the lease states it. Handle both.
  • RENT — baseRent plus any fixed taxes, opex, and parking for the step, and squareFootage when the lease states rent per step against a changing premises size. The GSA-only fields (fixedParking, annualTiRent, annualBsacRent, cpiIncreaseAmount) are null on every other lease type.
  • PERCENT_RENT — percent plus the sales breakpoint above which it applies, and breakpointTerm for breakpoints the lease states in prose.
  • ABATEMENT — the amount abated per period, and includesTaxAndOpex.
  • FEE — a recurring charge’s amount per step.
  • REFUND — a deposit or letter-of-credit burn-down. Dated by effectiveDate, derived from unitType/unitValue (months or years from commencement, or a date).
On a REFUND entry, read refundType before amount — it changes what the number means:reducedAmount saves you the arithmetic: it is the deposit as it stands at that step, with every reduction up to and including it applied.

Complex tags: components and rights

For COMPLEX tags, the substance is in tagComponents — polymorphic on its own kind: RENEWAL, EARLY_TERMINATION, EXPANSION, CONTRACTION, RIGHT_OF_FIRST_REFUSAL, RIGHT_OF_FIRST_OFFER, PURCHASE, AUTO_RENEWAL, TENANT_IMPROVEMENT, FEE, or OTHER. All components share rightStatus, effectiveDateOfRight, clause, customLabel, an optional amendingTag, and componentTags (refs to the constituent tags the component was assembled from, keyed by component field). Each kind then adds its own: Where a deadline is stated in relative terms rather than as a parseable date, the date field is null and a paired …Text field carries the source wording (expirationDateText, expirationDateOfRightText). The space-naming fields — expansionSpace, contractionSpace, offeredSpace, refusalSpace, encumberedSpaces — use the same shape and the same suite-name matching as a tag’s applicableSpaces. See Spaces and encumbrances.

Two status enums that are not the same thing

The two are orthogonal, independently-resolved signals — they can disagree, and neither overrides the other. A tag can be lifecycleStatus: ACTIVE while its component’s right is EXPIRED.

Amendment chains

Amendment chains track an option, not a lease. Every option carries a referenceId, and options that belong to the same chain share it. That shared key is what amendingTag exposes. amendingTag resolves to different things depending on what carries it: Three consequences worth designing around:
  1. The pointer runs backwards. amendingTag.amendedTagId is the id of the earlier tag. To find the current state of an option, start from the tag no other tag points at.
  2. amendingTag.effectiveDate is the referenced tag’s effective date, not this tag’s. For when the current version takes effect, read the component’s own effectiveDateOfRight.
  3. amendingTag is omitted on the first option in a chain, which is stored as self-referencing. Its absence means “chain start”, not “no chain”.
A single amendment can start a new chain, amend an existing one, or do both — and a lease commonly runs several chains in parallel. customLabel is the human-readable name of the family (“Option 1 — 5 Year Renewal”); options sharing a referenceId should share a customLabel, so it is a useful grouping key when presenting chains to a user. Superseded tags typically carry lifecycleStatus: VOID or STRICKEN, but treat that as corroboration rather than the primary signal — walk the chain.

Citations: tagSelections and pages

With include=tagSelections,pages, a tag brings its provenance: tagSelections are rectangles on document pages, and pages the geometry of those pages. Bounding boxes are expressed in basis points of page dimensions — each axis runs 0–10,000 where 10,000 is 100% of the page’s width or height, origin top-left. To place a box on a rendered page image:
and likewise for y, width, and height.