---
title: "Preview how a proposed import would affect Candor financial records."
method: POST
path: "/v1/imports/preview"
---

# Preview how a proposed import would affect Candor financial records.

`POST /v1/imports/preview`

## Request

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

Preview how a proposed import would affect Candor financial records.

## Headers

- `Idempotency-Key` string, required

## Request body

- CuratedImportManifest
  - `source_kind` string
  - `source_provider` 'agent_curated': Curated imports always use the agent-curated ingestion channel; native providers use separate source adapters.
  - `source_id` string
  - `file_name` string
  - `file_sha256` string
  - `authority` 'live_provider' | 'statement_reconciled' | 'agent_curated_unreconciled' | 'manual_correction' | 'external_claim_unverified': Evidence authority, not transport. statement_reconciled means the broker or source evidence was faithfully transcribed and reconciled; partial or unreconciled evidence uses agent_curated_unreconciled. manual_correction is a reviewed human correction.
  - `account` object, required: The account these records belong to.
    - `institution_name` string
    - `display_name` string, required: What the user calls this account.
    - `mask` string
    - `type` string, required: What kind of account this is, which decides how its balance reads.
    - `subtype` string
    - `currency` string, required: Three-letter uppercase ISO code, such as USD.
    - `source_account_id` string: Existing Candor source account id these records belong to. Use it to add, update, or remove holdings in a particular manual account; transaction imports require it either here or via the CLI --source-account flag.
    - `source_external_account_id` string
    - `account_identity_key` string
  - `period` object, required: The window this covers.
    - `start` string, required: First day the period covers, as an ISO calendar date.
    - `end` string, required: Last day the period covers, as an ISO calendar date.
    - `complete_statement_period` boolean
  - `balances` object
    - `opening` string
    - `closing` string: Exact observed account balance. For a manual investment account, use the displayed portfolio total so it can be reconciled to submitted holding values and included in balance history and net worth.
    - `as_of` string: When this balance was observed.
  - `holdings_scope` 'incremental' | 'complete': Incremental leaves omitted positions unchanged. Complete is allowed only for an existing agent-curated source_account_id with a dated closing balance and same-time holding rows that each include exact quantity or value; preview then turns every omitted active position into an explicit reversible removal.
  - `holdings` union[]
    - union
      - union
        - object
          - `row_key` string: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable, required: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable, required: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable, required: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable, required: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable, required: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string, required: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable, required: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable, required: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable, required: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable, required: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable, required: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
        - object
          - `row_key` string, required: Stable source-local key. Reuse it for later observations of the same position in this account.
          - `operation` 'upsert': Optional explicit upsert; omission also means upsert. A new row_key creates a position, while an existing row_key updates only supplied fields and preserves omitted fields. Set a clearable optional field to null to remove its stale value.
          - `security_id` string, nullable: Source security identifier when one is visible.
          - `symbol` string, nullable: Ticker or other short source symbol when visible.
          - `market` 'US' | 'null', nullable: Explicit supported listing market. Set US only when the evidence establishes that the symbol identifies a US-listed security; Candor will not infer market identity from account currency.
          - `name` string: Source-displayed name of the position.
          - `type` string, nullable, required: Source-displayed instrument kind. Derived quantity requires a supported unit-priced type of stock, equity, etf, fund, or mutual fund; options, bonds, and other multiplier-based instruments must remain value-only in P0.
          - `estimate_quantity` true: Opt in only for a current USD value-only US stock, equity, or ETF when future live valuation matters. Candor refreshes quotes in bounded internal chunks and returns a per-row estimated or value_only outcome. If the source value has a valuation time, send it in as_of as a fallback. An unavailable quote preserves that date on the value-only row, while a successful estimate replaces it with the quote observation time. If as_of does not align with the current price observation, Candor keeps the row value-only with a row-level time-mismatch warning instead of combining evidence from different times. Omit as_of only when the source valuation time is unknown. Do not combine estimation with holdings_scope complete, or use it for historical values, options, bonds, funds, private assets, or instruments requiring multipliers or face-value conventions.
          - `quantity` string, nullable: Exact units as a plain decimal. For a unit-priced instrument, the importing agent may derive this as value divided by exact per-unit price when both facts share the same valuation time and the derivation provenance is supplied. Leave it unknown for instruments requiring a contract multiplier or face-value convention.
          - `quantity_source` 'observed' | 'derived' | 'null', nullable: Whether quantity was visible in the source or derived by the importing agent from exact value and price. Derived also requires type, price_source_locator, and as_of.
          - `price` string, nullable: Exact displayed unit price as a non-negative plain decimal. It must be positive when quantity_source is derived.
          - `price_source_locator` string, nullable: Evidence locator for the exact price used to derive quantity. Required with quantity_source derived.
          - `value` string, nullable: Exact displayed position value as a plain decimal. Creating a holding requires value or quantity; an upsert that reuses an existing row_key may patch other supplied fields. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `currency` string: Three-letter uppercase ISO code; defaults to the account currency.
          - `cost_basis` string, nullable: Exact displayed total cost basis as a plain decimal. Observed source values beyond the currency exponent are half-even quantized and disclosed in preview; manual_correction remains strict.
          - `as_of` string, nullable: Row-specific valuation date or timestamp. Required when quantity_source is derived. With estimate_quantity, it is the fallback valuation time retained only when estimation is unavailable; a successful estimate uses the quote observation time instead. A fallback that does not align with the current price observation leaves the row value-only. Otherwise omit it when unknown instead of using today.
          - `source_locator` string: Agent-readable pointer back to the evidence, such as screenshot number and row.
          - `confidence` number: Caller-reported extraction confidence from zero to one, returned unchanged as agent_extraction_confidence. Omission is null; Candor does not assign confidence bands or change source authority.
      - union
        - unknown
        - unknown
  - `transactions` object[]
    - `row_key` string
    - `date` string, required: When the activity posted, as an ISO calendar date.
    - `amount` string, required: Exact money, as a plain signed decimal in the account's currency.
    - `currency` string: Three-letter uppercase ISO code, such as USD.
    - `description` string, required: The source description, kept as written so the record stays evidence.
    - `merchant_name` string
    - `category` string: The effective category this line governs.
    - `pending` boolean
    - `source_locator` string
    - `confidence` number: Caller-reported extraction confidence, returned unchanged as agent_extraction_confidence or null when omitted.
    - `reference_number` string
  - `terms` object[]: Source-backed account terms normalized into canonical typed fields. Omit row_key only when one logical value exists for the field; the fallback identity is then derived from terms_kind and field.
    - `row_key` string: Stable identity for this logical term across later imports.
    - `terms_kind` 'credit_card' | 'mortgage' | 'student_loan' | 'deposit' | 'loan', required: Canonical shape of the account terms.
    - `field` string, required: Consistent Candor field name across connected accounts, approved records, and imports, such as apr.purchase, minimum_payment, payment_due_date, or apy.
    - `value` union, required: Typed value observed for this field.
      - object
        - `kind` 'money', required: Selects an exact Money value.
        - `amount` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range.
          - string
          - string
          - string
      - object
        - `kind` 'percentage', required: Selects a non-negative percentage value.
        - `decimal` string, required: Exact percentage points as a decimal string, such as 19.25 for 19.25 percent.
      - object
        - `kind` 'date', required: Selects an ISO calendar date.
        - `value` string, date, required: Exact ISO calendar date for the term.
      - object
        - `kind` 'boolean', required: Selects a true-or-false term value.
        - `value` boolean, required: Observed true-or-false value.
      - object
        - `kind` 'string', required: Selects a bounded text term value.
        - `value` string, required: Observed text value for the term.
    - `observed_at` string, date-time: When the term was observed at its source.
    - `effective_from` string, date-time: When the observed term begins to apply.
    - `effective_through` string, date-time: Optional last instant when the observed term applies.
    - `source_locator` string: Human-auditable location in the source, such as a statement page or disclosure section.
  - `curation` object
    - `agent` string
    - `method` string
    - `notes` string

## Response `200`

Envelope with an import batch, row actions, issues, and suggested commands.

- 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)