---
title: "Parcel dossier (paid, provenance-first)"
method: GET
path: "/api/v1/parcels/{id}/report"
tags: ["Parcels"]
---

# Parcel dossier (paid, provenance-first)

`GET /api/v1/parcels/{id}/report`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/parcels/{id}/report`
- Auth: one of:
  - HTTP bearer
  - none

The Machine Storefront's per-parcel dossier: a single provenance-first JSON payload carrying every POPULATED field for the parcel as `{name, value}` (by default: no `sections`/`fields` params delivers everything the quote was priced on), plus the real deeds / comparable-sales / permits sub-tables (each comparable sale carries the read-time `similarity_score` 0–100 and `similarity_components` the free comps serve; they never change the price). The per-field receipts (source, as_of, confidence, coverage tier) are opt-in: `?include_provenance=true` adds a `provenance` map keyed by field name. `?sections=` (identity, valuation, owner, hazard, permits, deeds, market, demographics, `core`, `all`) and `?fields=` narrow the delivered field list; anything narrowed out is NAMED in `meta.projection.omitted_fields`, and the price never changes with the projection. A ~50 KB soft cap applies to the `fields` portion only. The GeoJSON boundary is held out as a separately-priced add-on the base payload omits.

PRICE (value-tiered, per parcel): price = clamp($5 x V(asset value) x R(data richness) x F(freshness), $2, $20). The exact amount for a given parcel is quoted, before payment, by GET /api/v1/storefront/availability?parcel_id=... and is what the 402 advertises in accepts[0].maxAmountRequired (USDC atomic units, 6 decimals).

ACCESS requires ONE of: (a) x402 pay-per-call -- send a base64 signed x402 PaymentPayload in the `X-PAYMENT` header; on a successful build the dossier is returned and the on-chain settlement receipt is in the `X-PAYMENT-RESPONSE` response header. No account is needed: the dossier, PEOPLE DATA included (owner names, owner mailing addresses, entity principals, deed and sale party names and addresses), is delivered to a wallet-only or credit-token buyer once the x402 payment settles or the credit debit succeeds, and the price is computed on exactly that body. An unpaid caller gets the 402 quote and nothing else. Send your API key with the payment to receive them. (b) A genuine PAID PropRaven subscription entitlement -- the dossier is served on the subscription invoice. Being merely authenticated is NOT sufficient: a free-tier key, or a self-service first-party key with no paid plan, receives a 402. (c) Anything else -> HTTP 402 whose `accepts` array carries the exact x402 payment requirements for this parcel.

## Path parameters

- `id` string, required

## Query parameters

- `county_fips` string
- `sections` string
- `fields` string
- `include_provenance` boolean

## Headers

- `X-PAYMENT` string

## Response `200`

The parcel dossier (provenance-first JSON).

- ParcelDossier: The paid, provenance-first parcel dossier returned by GET /parcels/{id}/report. Every populated field is delivered as `{name, value}`; the receipts (source, as_of, confidence, coverage) come as the opt-in `provenance` map (`include_provenance=true`), keyed by field name. The deeds/comps/permits sub-tables carry real rows; the GeoJSON boundary is a separately-priced add-on omitted from the base payload. Nulls/empties are dropped (see meta.field_count), not returned as null; columns a `sections`/`fields` projection leaves out are named in `meta.projection.omitted_fields`.
  - `parcel` object: Parcel identity.
    - `canonical_id` string: state_fips:county_fips:parcel_id.
    - `id` string, nullable: PropRaven row UUID when the serving row carried one.
    - `state_fips` string
    - `county_fips` string: 3-digit within-state county code (the parcels_serving convention).
    - `county_fips_3` string: Same as county_fips, named for its width.
    - `county_fips_5` string
    - `parcel_id` string
    - `state` string, nullable
    - `address` string, nullable
  - `fields` object[]: Every populated field the delivery kept, as {name, value}. The receipt properties below are present only on the pure assembler's unprojected output; on a delivered dossier they live in the `provenance` map when `include_provenance=true` was requested.
    - `name` string
    - `value` unknown
    - `source` string: Field-level source label from the sealed catalog.
    - `as_of` string, nullable
    - `confidence` number, nullable: 0..1 FIELD-LEVEL coverage (this parcel's state, else national); null when uncatalogued. Not a per-cell probability -- see confidence_basis.
    - `confidence_basis` string
    - `national_coverage` number, nullable
    - `state_coverage` number, nullable
    - `tier` string, nullable: prime|strong|good|partial|sparse|trace, re-derived from the applicable (state, else national) coverage.
    - `grain` string, nullable
    - `section` string, nullable
    - `flags` string[]
    - `catalogued` boolean: False when the column is absent from the sealed catalog (source unknown).
  - `sections` object: Real sub-tables from the serving relations.
    - `deeds` DossierSubSection: One real sub-table (deeds, comps, or permits) in a dossier, with the exact serving relation it came from and that relation's own watermark (each is NOT pinned to the parcels epoch).
      - `relation` string: The serving relation the rows came from.
      - `as_of` string, nullable: Watermark for this relation.
      - `status` 'ok' | 'empty'
      - `row_count` integer
      - `note` string
      - `rows` object[]
      - `similarity_basis` string: comps: present when rows exist; each comps row carries `similarity_score` (0–100) and `similarity_components`, computed at read time exactly as GET /parcels/{id}/comps computes them. They do not affect the dossier price.
      - `similarity_method` string: comps: how `similarity_score` is computed.
    - `comps` DossierSubSection: One real sub-table (deeds, comps, or permits) in a dossier, with the exact serving relation it came from and that relation's own watermark (each is NOT pinned to the parcels epoch).
      - `relation` string: The serving relation the rows came from.
      - `as_of` string, nullable: Watermark for this relation.
      - `status` 'ok' | 'empty'
      - `row_count` integer
      - `note` string
      - `rows` object[]
      - `similarity_basis` string: comps: present when rows exist; each comps row carries `similarity_score` (0–100) and `similarity_components`, computed at read time exactly as GET /parcels/{id}/comps computes them. They do not affect the dossier price.
      - `similarity_method` string: comps: how `similarity_score` is computed.
    - `permits` DossierSubSection: One real sub-table (deeds, comps, or permits) in a dossier, with the exact serving relation it came from and that relation's own watermark (each is NOT pinned to the parcels epoch).
      - `relation` string: The serving relation the rows came from.
      - `as_of` string, nullable: Watermark for this relation.
      - `status` 'ok' | 'empty'
      - `row_count` integer
      - `note` string
      - `rows` object[]
      - `similarity_basis` string: comps: present when rows exist; each comps row carries `similarity_score` (0–100) and `similarity_components`, computed at read time exactly as GET /parcels/{id}/comps computes them. They do not affect the dossier price.
      - `similarity_method` string: comps: how `similarity_score` is computed.
  - `boundary` object: The GeoJSON boundary add-on. In the base dossier included=false and geometry is absent; a phase-2 add-on purchase populates geometry.
    - `code` string
    - `price` Money: A money amount as a decimal string plus its currency code.
      - `amount` string, required
      - `currency` string, required
    - `included` boolean
    - `purchasable` boolean
    - `available` boolean, nullable
    - `relation` string
    - `note` string
    - `geometry` unknown
  - `meta` object: Dossier-level provenance and pricing.
    - `catalog_version` string
    - `catalog_seal` string
    - `contract_version` number
    - `snapshot_as_of` string, nullable
    - `generated_at` string
    - `price` Money: A money amount as a decimal string plus its currency code.
      - `amount` string, required
      - `currency` string, required
    - `currency` string
    - `field_count` number: Populated fields actually emitted.
    - `catalog_sellable_fields` number
    - `catalog_total_columns` number
    - `sections_included` string[]
    - `geometry_included` boolean
    - `confidence_basis` string
    - `provenance_note` string
    - `license` string, uri: The data license that governs this dossier's data (the Data license section of the Terms of Use).
    - `entitlement` object
      - `gated` boolean
      - `method` string
      - `note` string
  - `people_fields` PeopleFieldsWithheld: Additive marker on a record (or list) whose people fields were withheld because the caller has no PropRaven account. People fields are owner names, owner mailing / owner-address columns, entity principals, recorded-document party names and addresses (grantor/grantee, buyer/seller, prior/new owner), permit applicant names and the resolved `owner_contact` block. Withheld keys are kept and set to null (lists of people records become []), so the record's shape does not change. Send an API key (`Authorization: Bearer pz_...`) or call from a signed-in session; on the paid products a settled x402 payment or a prepaid credit debit also delivers people data.
    - `status` 'withheld', required
    - `code` 'account_required', required
    - `reason` 'people_data_requires_account', required
    - `note` string, required

## Other responses

- `400`: A query or body parameter is invalid. Nothing was read or charged.
- `401`: Missing, malformed or invalid credential.
- `402`: Payment required. This is a paid, value-tiered dossier: the response body's accepts[0].maxAmountRequired carries this parcel's exact price in USDC atomic units. Pay per call via x402 (send the `X-PAYMENT` header), or hold a paid PropRaven subscription. A free-tier or self-service first-party key with no paid plan also receives this 402.
- `404`: The resource (or the endpoint) does not exist.
- `405`: The endpoint exists but does not support this method. `Allow` lists the methods it does.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error. The body never carries database or driver text.

---

[API](https://skmtc.dev/propraven/apis/propraven-api.md) · [All operations](https://skmtc.dev/propraven/apis/propraven-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propraven/apis/propraven-api/revisions/37f8158c4eda?raw)