{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/propraven-com/json-schema/propraven-com-lead-feed-preview-schema.json",
  "title": "LeadFeedPreview",
  "description": "The FREE preview (preview=true). `count` and `quote` are exactly what a paid call would deliver and charge.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/propraven-com-leads-api-openapi.yml#/components/schemas/LeadFeedPreview",
  "type": "object",
  "required": [
    "signal",
    "geo",
    "count",
    "count_capped_at_limit",
    "quote",
    "preview",
    "sample",
    "note"
  ],
  "properties": {
    "signal": {
      "type": "string"
    },
    "geo": {
      "type": "object",
      "description": "The resolved request geography and filters.",
      "required": [
        "state",
        "state_fips",
        "county_fips",
        "zip",
        "value_min",
        "value_max",
        "mail_ready",
        "limit"
      ],
      "properties": {
        "state": {
          "type": "string"
        },
        "state_fips": {
          "type": "string"
        },
        "county_fips": {
          "type": [
            "string",
            "null"
          ]
        },
        "zip": {
          "type": [
            "string",
            "null"
          ]
        },
        "value_min": {
          "type": [
            "integer",
            "null"
          ]
        },
        "value_max": {
          "type": [
            "integer",
            "null"
          ]
        },
        "mail_ready": {
          "type": "boolean"
        },
        "limit": {
          "type": "integer"
        },
        "tax_delinquent": {
          "type": "boolean"
        }
      }
    },
    "count": {
      "type": "integer",
      "description": "Leads that will be / were delivered: min(matching rows, limit). This is the priced quantity."
    },
    "count_capped_at_limit": {
      "type": "boolean",
      "description": "True when the count stopped at `limit` -- more leads exist beyond this pull."
    },
    "quote": {
      "$ref": "#/$defs/LeadsQuote"
    },
    "preview": {
      "type": "boolean",
      "enum": [
        true
      ]
    },
    "sample": {
      "type": "array",
      "description": "Up to three MASKED leads: APN truncated to state:county, house number stripped, owner name withheld. Enough to judge the set, not enough to work it.",
      "items": {
        "$ref": "#/$defs/Lead"
      }
    },
    "note": {
      "type": "string"
    },
    "coverage_note": {
      "type": "string",
      "description": "Present only when a known data gap explains an empty result (e.g. the owner-portfolio rollup's unpopulated state columns). Nothing is charged in that case."
    },
    "tax_delinquency_filter": {
      "$ref": "#/$defs/TaxDelinquencyFilter"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "ContactSource": {
      "type": "object",
      "required": [
        "authority",
        "dataset",
        "url"
      ],
      "properties": {
        "authority": {
          "type": "string",
          "description": "Who published the value, e.g. the county assessor."
        },
        "dataset": {
          "type": "string"
        },
        "url": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false
    },
    "Lead": {
      "type": "object",
      "description": "One delivered lead. Signal-specific strength fields are flattened alongside the common keys (e.g. years_held + hold_tier for long_hold; profit + profit_pct + flip_tier for flip; land_improvement_ratio for high_land_ratio/distressed; property_count + states_list for portfolio_owner).",
      "required": [
        "canonical_id",
        "address",
        "city",
        "state",
        "zip",
        "assessed_value",
        "lead_score",
        "owner_address",
        "owner_city",
        "owner_state",
        "is_out_of_state",
        "last_sale_date",
        "last_sale_price",
        "owner_name",
        "masked",
        "provenance"
      ],
      "properties": {
        "canonical_id": {
          "type": "string",
          "description": "state_fips:county_fips3:parcel_id (the assessor APN, never a PropRaven UUID). Null on the owner-grain portfolio_owner cohort. MASKED to \"37:183:...\" in the free preview."
        },
        "address": {
          "type": [
            "string",
            "null"
          ],
          "description": "Situs address. House number stripped in the free preview."
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "state": {
          "type": [
            "string",
            "null"
          ]
        },
        "zip": {
          "type": [
            "string",
            "null"
          ]
        },
        "assessed_value": {
          "type": [
            "number",
            "null"
          ],
          "description": "Total assessed value (sell price on the flip cohort)."
        },
        "lead_score": {
          "type": [
            "number",
            "null"
          ],
          "description": "Deterministic 1-100: the signal's base intent plus a bounded bonus from that signal's own strength column. Re-derivable, never random."
        },
        "owner_address": {
          "type": [
            "string",
            "null"
          ]
        },
        "owner_city": {
          "type": [
            "string",
            "null"
          ]
        },
        "owner_state": {
          "type": [
            "string",
            "null"
          ]
        },
        "is_out_of_state": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "last_sale_date": {
          "type": [
            "string",
            "null"
          ]
        },
        "last_sale_price": {
          "type": [
            "number",
            "null"
          ]
        },
        "owner_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Withheld (null) in the free preview. Delivered leads go to accounts only."
        },
        "masked": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Present and true ONLY on free-preview sample leads."
        },
        "provenance": {
          "type": "object",
          "required": [
            "source",
            "source_datasets",
            "as_of",
            "as_of_basis",
            "serving_epoch",
            "freshness_status",
            "catalog_reference",
            "note"
          ],
          "properties": {
            "source": {
              "type": [
                "string",
                "null"
              ]
            },
            "source_datasets": {
              "type": "array",
              "items": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "as_of": {
              "type": [
                "string",
                "null"
              ],
              "description": "The serving epoch's generated_at."
            },
            "as_of_basis": {
              "type": [
                "string",
                "null"
              ]
            },
            "serving_epoch": {
              "type": [
                "string",
                "null"
              ]
            },
            "freshness_status": {
              "type": [
                "string",
                "null"
              ]
            },
            "catalog_reference": {
              "type": "object",
              "required": [
                "catalog_version",
                "catalog_generated_at",
                "catalog_seal"
              ],
              "properties": {
                "catalog_version": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "catalog_generated_at": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "catalog_seal": {
                  "type": "object",
                  "required": [
                    "algorithm",
                    "value",
                    "covers"
                  ],
                  "properties": {
                    "algorithm": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "value": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "covers": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            },
            "note": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "owner_contact": {
          "$ref": "#/$defs/LeadOwnerContact",
          "description": "Delivered leads only: the owner's best mailing address (ONE column family, with its ZIP), flagged mail_ready. Absent from the free preview."
        }
      },
      "additionalProperties": false
    },
    "LeadOwnerContact": {
      "type": "object",
      "description": "The owner's best mailing address on a delivered lead (account holders only). Lead pulls do not run the per-parcel permit phone lookup (`phone_status` is always not_checked); call GET /api/v1/owners/card for the full card.",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "resolved",
            "not_found",
            "unavailable"
          ],
          "description": "unavailable = the contact read failed for this delivery (never a silently missing block)."
        },
        "mailing": {
          "oneOf": [
            {
              "$ref": "#/$defs/MailingAddress"
            },
            {
              "type": "null"
            }
          ]
        },
        "mail_ready": {
          "type": "boolean"
        },
        "phone_status": {
          "type": "string",
          "enum": [
            "not_checked"
          ]
        },
        "hidden_low_confidence": {
          "type": "integer"
        }
      }
    },
    "LeadsQuote": {
      "type": "object",
      "description": "The per-lead price quote. IDENTICAL in the free preview and in the 402/charge -- the previewed price is the paid price.",
      "required": [
        "per_lead",
        "per_lead_usd",
        "total",
        "total_usd",
        "total_atomic_usdc",
        "asset",
        "count",
        "signal",
        "tier",
        "tier_label",
        "breakdown",
        "pay",
        "note"
      ],
      "properties": {
        "per_lead": {
          "$ref": "#/$defs/Money"
        },
        "per_lead_usd": {
          "type": "number",
          "description": "Unit price to 4dp: clamp($0.25 x S x V, $0.05, $1.00)."
        },
        "total": {
          "$ref": "#/$defs/Money"
        },
        "total_usd": {
          "type": "number",
          "description": "The amount actually charged: min(count x per_lead, $20)."
        },
        "total_atomic_usdc": {
          "type": "string",
          "description": "total_usd in USDC atomic units (6dp) -- what the 402 advertises as maxAmountRequired."
        },
        "asset": {
          "type": "string"
        },
        "count": {
          "type": "integer",
          "description": "Leads priced = leads delivered."
        },
        "signal": {
          "type": "string"
        },
        "tier": {
          "type": "string",
          "description": "Asset-value tier, from the median assessed value of the delivered set.",
          "enum": [
            "low",
            "mid",
            "high",
            "premium"
          ]
        },
        "tier_label": {
          "type": "string"
        },
        "breakdown": {
          "type": "object",
          "description": "The dials, so the price is auditable.",
          "required": [
            "base_per_lead",
            "S",
            "V",
            "per_lead_raw",
            "total_raw",
            "capped"
          ],
          "properties": {
            "base_per_lead": {
              "type": "number"
            },
            "S": {
              "type": "number",
              "description": "Signal-strength multiplier (absentee 1.0 ... distressed 1.9)."
            },
            "V": {
              "type": "number",
              "description": "Asset-value tier multiplier (low 0.7, mid 1.0, high 1.5, premium 2.2)."
            },
            "per_lead_raw": {
              "type": "number",
              "description": "Per-lead price BEFORE the [$0.05, $1.00] clamp."
            },
            "total_raw": {
              "type": "number",
              "description": "count x per_lead BEFORE the $20 per-call cap."
            },
            "capped": {
              "type": "boolean",
              "description": "True when the $20 cap bound -- volume beyond it was free."
            }
          }
        },
        "pay": {
          "type": "array",
          "items": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "note": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "MailingAddress": {
      "type": "object",
      "description": "One mailing address, read from ONE address column family of the record (owner_mailing_* or owner_*), never a street from one family and a ZIP from the other.",
      "required": [
        "basis",
        "line1",
        "city",
        "state",
        "zip5",
        "zip4",
        "mail_ready",
        "po_box",
        "equals_situs",
        "zip_conflict",
        "parcels_citing",
        "parcels_citing_basis",
        "label",
        "source",
        "as_of",
        "as_of_basis",
        "grade"
      ],
      "properties": {
        "basis": {
          "type": "string",
          "description": "Where the address came from, e.g. owner_mailing, owner_address, deed_grantee."
        },
        "line1": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "zip5": {
          "type": "string"
        },
        "zip4": {
          "type": [
            "string",
            "null"
          ]
        },
        "mail_ready": {
          "type": "boolean",
          "description": "Street, city, state and a 5-digit ZIP are all present and consistent."
        },
        "po_box": {
          "type": "boolean"
        },
        "equals_situs": {
          "type": "boolean",
          "description": "The mailing address is the property itself (owner-occupied)."
        },
        "zip_conflict": {
          "type": "boolean"
        },
        "parcels_citing": {
          "type": "number",
          "description": "Owner (name) cards only: how many of the owner's parcels carry this address."
        },
        "parcels_citing_basis": {
          "type": "string"
        },
        "label": {
          "type": "string",
          "description": "The address as one mailing label."
        },
        "source": {
          "$ref": "#/$defs/ContactSource"
        },
        "as_of": {
          "type": "string"
        },
        "as_of_basis": {
          "type": "string"
        },
        "grade": {
          "type": "string",
          "description": "A = the authority's own complete record; D = contradictory (hidden unless include_low_confidence=true).",
          "enum": [
            "A",
            "B",
            "C",
            "D"
          ]
        }
      },
      "additionalProperties": false
    },
    "Money": {
      "type": "object",
      "description": "A money amount as a decimal string plus its currency code.",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "string"
        },
        "currency": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "TaxDelinquencyFilter": {
      "type": "object",
      "description": "Present when `tax_delinquent=true` was applied.",
      "required": [
        "applied",
        "statuses",
        "note"
      ],
      "properties": {
        "applied": {
          "type": "boolean"
        },
        "statuses": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "note": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  }
}