---
title: "Owner intelligence report (paid, priced per resolution; account required) — with a free preview"
method: GET
path: "/api/v1/owners/{name}/report"
tags: ["Owners"]
---

# Owner intelligence report (paid, priced per resolution; account required) — with a free preview

`GET /api/v1/owners/{name}/report`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/owners/{name}/report`
- Auth: HTTP bearer

The Machine Storefront's owner intelligence report: every parcel nationwide whose OWNER-OF-RECORD name matches one owner NAME's realistic spellings (or a public company TICKER's hand-curated entity list), deduped nationally and priced PER RESOLUTION.

ACCOUNT REQUIRED (every mode, including the free preview): an API key (`Authorization: Bearer pz_...`) or a signed-in session. Payment alone (an x402 `X-PAYMENT` header or a prepaid `X-CREDIT-TOKEN`) is not an account. An anonymous call is refused with HTTP 401, `code: "account_required"`, `reason: "owner_lookup_requires_account"`, before any read, payment verification or credit debit.

MATCHING is spelling matching, NOT a verified corporate or beneficial-ownership link: different owners can share a spelling and some of one owner's spellings can be missed. Every property carries `match_basis` (exact_spelling = the record's owner name is the requested name after case/punctuation/whitespace normalization; variant = matched only through an expanded suffix/hyphen/N.A. spelling; ticker_curated = on the hand-curated ticker list) and `match_confidence: "candidate"`. The report carries: owner {query_name, ticker, entity_type, resolved_variants, match}, summary {count, total_assessed_value, total_acreage, states, by_state[]}, properties[] (each with match_basis, canonical_id, address, valuation, lot/building, last sale, property_type), and provenance {as_of, source}.

PRICE: per resolution = clamp($1.75 x P(portfolio size) x V(portfolio value), $0.25, $20). P is log-scaled on the distinct parcel count the match uncovers (the dominant axis); V is log-scaled on the summed assessed value; a missing value floors V rather than raising the price. A match that uncovers zero parcels is returned free and never charged. The exact price is advertised in the 402's accepts[0].maxAmountRequired (USDC atomic units, 6 decimals).

FREE PREVIEW: add preview=true for the summary (count, total value, states spanned, entity type), the exact price, and up to three MASKED sample properties (APN truncated to state:county, house number stripped). No payment; an account is still required.

PAID ACCESS (preview omitted), for an authenticated account, requires ONE of: (a) x402 pay-per-call — send a base64 signed x402 PaymentPayload in the `X-PAYMENT` header alongside your credentials; on a successful build the full portfolio is returned and the on-chain settlement receipt is in the `X-PAYMENT-RESPONSE` response header. (b) A prepaid `X-CREDIT-TOKEN` balance. (c) A genuine PAID PropRaven subscription entitlement (owner reports are included). Being merely authenticated is NOT sufficient. (d) Anything else -> HTTP 402 whose `accepts` array carries the exact payment requirements for this resolution.

## Path parameters

- `name` string, required

## Query parameters

- `ticker` string
- `state` string
- `limit` integer
- `offset` integer
- `preview` boolean

## Headers

- `X-PAYMENT` string

## Response `200`

The owner report (paid or entitled), or — with preview=true — the free masked summary, or a free $0 empty result when the pierce uncovers nothing.

- object
  - `owner` object, required
    - `query_name` string, required
    - `ticker` string, nullable, required
    - `entity_type` string, required
    - `resolved_variants` string[], required
    - `match` object, required
      - `method` string, required
      - `confidence` string, required
      - `verified_corporate_link` boolean, required
      - `basis_counts` object, required
        - `exact_spelling` number, required
        - `variant` number, required
        - `ticker_curated` number, required
      - `basis_counts_scope` string, required
      - `note` string, required
  - `filter` object, required
    - `state_fips` string, nullable, required
  - `summary` object, required
    - `count` integer, required
    - `total_assessed_value` integer, required
    - `total_acreage` number, required
    - `states` number[], required
    - `by_state` object[], required
      - `state` string, nullable, required
      - `state_fips` string, required
      - `abbr` string, nullable, required
      - `count` integer, nullable, required
      - `total_value` integer, nullable, required
      - `total_acreage` number, nullable, required
  - `quote` object, required
    - `price` object, required
      - `amount` string, required
      - `currency` string, required
    - `price_usd` number, required
    - `price_atomic_usdc` string, required
    - `asset` string, required
    - `parcel_count` integer, required
    - `band` string, required
    - `band_label` string, required
    - `breakdown` object, required
      - `base` number, required
      - `P` number, required
      - `V` number, required
      - `price_raw` number, required
      - `capped` boolean, required
    - `pay` string[], required
    - `note` string, required
  - `preview` boolean, required
  - `sample` object[], required
    - `canonical_id` string, required
    - `address` string, nullable, required
    - `city` string, nullable, required
    - `state` string, nullable, required
    - `zip` string, nullable, required
    - `total_assessed_value` number, nullable, required
    - `property_type` string, nullable, required
    - `match_basis` string, required
    - `match_confidence` string, nullable, required
  - `note` string, required

## Other responses

- `400`: Invalid owner name (unresolvable / too generic) or invalid state.
- `401`: No account: an anonymous caller (including one presenting only an x402 X-PAYMENT header or an X-CREDIT-TOKEN) gets problem+json with code `account_required` and reason `owner_lookup_requires_account`; or a present-but-invalid API key.
- `402`: Payment required. accepts[0].maxAmountRequired carries this resolution's exact price (portfolio size x value, floor $0.25, cap $20) in USDC atomic units. Pay per call via x402, hold a paid PropRaven subscription, or re-call with preview=true for the free masked summary.
- `405`: The endpoint exists but does not support this method. `Allow` lists the methods it does.
- `429`: Rate limited.
- `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)