---
title: "Preview property setup or a manual observation. Does not affect net worth until apply. Automatic mode retrieves two paid provider endpoints within the configured quota."
method: POST
path: "/v1/properties/preview"
---

# Preview property setup or a manual observation. Does not affect net worth until apply. Automatic mode retrieves two paid provider endpoints within the configured quota.

`POST /v1/properties/preview`

## Request

- Base URL: `https://api.candor.money`
- URL: `https://api.candor.money/v1/properties/preview`
- Auth: HTTP bearer

Manage tracked property evidence through the reviewed preview and apply flow.

## Headers

- `Idempotency-Key` string, required

## Request body

- PropertyInput: Full property setup snapshot. Omitted mortgage and debt-free fields must not be inferred from provider data. To update a tracked property, include property_id and the complete intended setup. An older manual observation extends history without replacing current tracking. The preview effect identifies history_only versus tracking_update.
  - `property_id` string: Existing property to update; omit to create a property. Use its canonical id to prevent duplicate assets.
  - `name` string, required: User-facing name, such as Home or Oak Street rental.
  - `address` object, required: Physical property identity and location used for source lookup and duplicate detection.
    - `street` string, required: Street address including the building number.
    - `unit` string: Apartment or unit identity, when applicable.
    - `city` string, required: City or locality.
    - `region` string, required: State or region; use the two-letter state abbreviation for US estimates.
    - `postal_code` string, required: Postal code; US automated estimates use ZIP codes.
    - `country` string, required: ISO country code. Automatic estimates currently support US only.
  - `property_type` 'Single Family' | 'Condo' | 'Townhouse' | 'Manufactured' | 'Multi-Family' | 'Apartment' | 'Other', required: Physical property type. Multi-family automatic rent is per unit and never summed as the building's rent.
  - `ownership_percent` number, required: Owned share, from greater than zero through 100 percent. Value and whole-property rent contributions use this share. Mortgage balances remain as recorded in the linked account.
  - `debt_free` boolean, required: True only when the property is known to have no secured debt. False with no linked mortgage leaves equity unknown.
  - `mortgage_source_account_id` string: Visible loan account already in this workspace. Linking it does not add another liability. One loan can be linked to one property.
  - `mortgage_balance_scope` 'full_account': Explicit confirmation that the entire linked loan balance belongs in this property equity calculation. Omit when joint debt responsibility is unresolved; equity remains unknown. Never infer from ownership_percent. Net worth continues to count the account balance once.
  - `estimate_provider` string: Automated estimate provider identifier. Currently rentcast; omitted uses the existing connection or RentCast for a new connection. Stored with the provider property ID to namespace external identities.
  - `tracking_mode` 'automatic' | 'manual', required: Automatic connects monthly US estimates. Manual pins imported or entered observations and prevents automatic replacement.
  - `value` union: Canonical Money text returned as one self-contained JSON string with the currency's exact decimal places.
    - string
    - string
    - string
  - `monthly_rent` union: Canonical Money text returned as one self-contained JSON string with the currency's exact decimal places.
    - string
    - string
    - string
  - `as_of` string, date: Date of the manual observation, required in manual mode. Must not be in the future. Omit for automatic mode.
  - `source_label` string: Name of the appraisal, statement, or source behind the manual observation.
  - `source_locator` string: Optional evidence URI or document reference; retained as provenance, never fetched automatically.

## Response `200`

Property operation result.

- ResponseEnvelope
  - `schema_version` string, required
  - `generated_at` string, date-time, required
  - `request_id` string, required
  - `status` 'success' | 'partial_success' | 'action_required' | 'error', required
  - `user_message` string: Optional concise user-safe message the calling agent may adapt.
  - `data_freshness` DataFreshness
    - `balances_last_synced_at` string
    - `coverage` 'complete' | 'partial' | 'stale' | 'unavailable', required
    - `holdings_last_synced_at` string
    - `transactions_last_synced_at` string
  - `metadata` object: Response-level protocol metadata such as package compatibility and workspace opening identity or timing. It is not financial workspace data and must not be treated as attention.
    - `view_url` string, uri: Authenticated dashboard destination related to this response. May open a section rather than reproduce the returned records or filters. Per-record view_url values identify exact supported record views. Use returned URLs instead of constructing paths.
  - `warnings` object[], required
  - `errors` AgentError[], required
    - `code` string, required
    - `expires_at` string
    - `idempotency_key` string: Stable key to reuse when retrying this identical logical operation.
    - `message` string, required
    - `recovery_url` string, uri
    - `required_capability` string
    - `retry_after_seconds` integer: Machine-actionable delay before retrying the identical logical operation.
    - `retryable` boolean, required
    - `suggested_command` string
  - `next_actions` AgentAction[], required
    - `intent` string, required
    - `command` string, required
    - `args` object, required
    - `shell` string, required
  - `action` WorkspaceAction
    - `id` string, required
    - `operation` string, required
    - `reason` string, required
    - `root_action_id` string, required
    - `parent_action_id` string
    - `task_key` string
    - `status` 'started' | 'succeeded' | 'refused' | 'failed', required
    - `created_at` string, date-time, required
    - `completed_at` string, date-time
  - `data` object, nullable, required: Operation-specific result data, or null when the request ends in an error.

## Other responses

- `default`: Structured Candor error envelope with machine-readable codes, recovery guidance, and retry timing when applicable.

---

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