> ## Documentation Index > Fetch the complete documentation index at: https://docs.itoflow.ai/llms.txt > Use this file to discover all available pages before exploring further. # Validate uploaded paper portfolio import > Validate holdings and cash for a managed paper-portfolio import. This preflight returns the complete review result and an approval token but does not create a portfolio. Operation ID: post__portfolios_import_validate. ## OpenAPI ````yaml /openapi/itoflow-public.openapi.json post /portfolios/import/validate openapi: 3.1.0 info: description: >- All Itoflow APIs are experimental and may change without notice. Read-only operations marked interactive can be tried from the documentation; the others are reference-only. title: Itoflow Developer API version: 1.0.0 servers: - description: Itoflow API url: https://api.itoflow.ai security: [] tags: - name: Account - name: Billing - name: Brokers - name: Chat - name: Connected MCP servers - name: GitHub - name: Market data - name: Monitors - name: Notifications - name: Portfolios - name: Risk runs - name: Sharing and data - name: Strategies paths: /portfolios/import/validate: post: tags: - Portfolios summary: Validate uploaded paper portfolio import description: >- Validate holdings and cash for a managed paper-portfolio import. This preflight returns the complete review result and an approval token but does not create a portfolio. Operation ID: post__portfolios_import_validate. operationId: post__portfolios_import_validate requestBody: content: application/json: schema: additionalProperties: false description: >- Approved portfolio upload import request for a managed paper portfolio. properties: approval_token: description: >- Signed approval token returned by import preflight for the approved draft. maxLength: 4000 minLength: 1 type: string draft: additionalProperties: false description: >- User-approved edited draft to import as a managed paper portfolio. properties: approved_at: anyOf: - format: date-time type: string - format: date-time type: string description: >- ISO timestamp set when the user approved this edited draft. cash: default: [] description: >- Optional parsed cash balances to import alongside holdings. items: additionalProperties: false description: >- One parsed cash balance row for the editable portfolio upload review. properties: amount: description: >- Cash amount in the row currency; negative for borrowed cash such as a margin loan. Never a security quantity or portfolio total unless explicitly a cash balance. pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: string currency: description: >- Ledger currency established by source or user edit evidence, or by verified Itoflow provider symbol metadata; never infer it from unverified symbol text, exchange, broker, country, or filename. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string included: default: true description: >- Whether this cash row should be imported if the user confirms. type: boolean issues: default: [] description: >- Cash-row parser or validation issues; error severity blocks confirmation. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array row_id: description: >- Stable cash row id used for edits, validation errors, and import diagnostics. maxLength: 80 minLength: 1 type: string source: description: >- Short source note for the cash row, such as filename, screenshot area, or sheet name. maxLength: 240 type: string required: - amount - row_id type: object type: array draft_id: description: >- Stable id for this parsed portfolio draft across review revisions. maxLength: 120 minLength: 1 type: string execution_mode: description: >- Always paper for chat portfolio uploads; this import cannot create a live portfolio. enum: - paper type: string holdings: description: Parsed holding rows for user review and possible import. items: additionalProperties: false description: >- One parsed holding row for the editable portfolio upload review. properties: cost_basis: description: >- Optional average entry price per one share/unit in currency and price_unit terms; omit when unknown and never use 0 as a placeholder; never copy total cost, total invested, or current value into this field. A deterministic per-unit value reconciled from quantity, market value, signed unrealized P&L, explicit currency evidence, and available current-price evidence is allowed when the derivation is recorded as a row warning. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string currency: description: >- Ledger currency established by source or user edit evidence, or by verified Itoflow provider symbol metadata; never infer it from unverified symbol text, exchange, broker, country, or filename. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string included: default: true description: >- Whether this holding row should be imported if the user confirms. type: boolean issues: default: [] description: >- Row-scoped parser or validation issues; error severity blocks confirmation. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array price_unit: default: NATIVE description: >- Quote denomination for unit_value and cost_basis; use NATIVE unless the source or selected Itoflow symbol metadata explicitly quotes GBX, ZAC, or ILA. enum: - NATIVE - GBX - ZAC - ILA type: string quantity: description: >- Signed number of shares or units held: positive for a long, negative for a short. Never market value, allocation weight, total cost, or cash. pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: string row_id: description: >- Stable row id used for edits, validation errors, and import diagnostics. maxLength: 80 minLength: 1 type: string side: description: >- Optional position side copied from a side column: long or L, short or S, in any case. A short side turns a positive quantity negative; omit side when the quantity already carries its sign. pattern: >- ^(?:[Ll][Oo][Nn][Gg]|[Ll]|[Ss][Hh][Oo][Rr][Tt]|[Ss])$ type: string source: description: >- Short source note for the row, such as filename, screenshot area, or sheet name. maxLength: 240 type: string symbol: description: >- Fully qualified holding symbol in SYMBOL.EXCHANGE format, matching symbol_resolution.symbol after lookup. maxLength: 80 minLength: 1 type: string symbol_resolution: additionalProperties: false description: >- Selected Itoflow symbol lookup result for a holding; this is not free text. properties: code: description: >- Provider ticker code from the selected Itoflow symbol result. maxLength: 40 minLength: 1 type: string currency: description: >- Currency or quote-unit alias returned by the selected Itoflow symbol result. pattern: ^(?:[A-Z]{3}|GBp)$ type: - string - 'null' exchange: description: >- Exchange code from the selected Itoflow symbol result. maxLength: 40 minLength: 1 type: string name: description: >- Instrument name from the selected Itoflow symbol result. maxLength: 240 minLength: 1 type: string symbol: description: >- Fully qualified Itoflow symbol selected from lookup, e.g. AAPL.US. maxLength: 80 minLength: 1 type: string type: description: >- Instrument type from the selected Itoflow symbol result when known. maxLength: 120 type: - string - 'null' required: - code - exchange - name - symbol type: object unit_scale: description: >- Required only for supported quote subdivisions GBX, ZAC, or ILA; omit for NATIVE price units. enum: - '0.01' type: string unit_value: description: >- Optional parsed current market price per one share/unit in currency and price_unit terms; omit when unknown. Import validation ignores this field and resolves provider current prices for display when available; never total row value, market value, account value, invested value, or position value. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string required: - quantity - row_id - symbol type: object maxItems: 3000 type: array parser_warnings: default: [] description: >- Draft-level parsing warnings from ambiguous or incomplete source evidence. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array portfolio_name: description: >- User-editable name for the managed paper portfolio to create. maxLength: 100 minLength: 1 type: string portfolio_type: description: >- Always managed for chat portfolio uploads; this import cannot create a reference portfolio. enum: - managed type: string portfolio_value: additionalProperties: false description: >- Optional user/source value to reconcile with quantity-bearing holdings. Omit when the current provider-priced mark is the only known value. properties: amount: description: Decimal string without commas or currency symbols. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string as_of_date: description: >- Date of the user or source portfolio value, not the import timestamp. pattern: ^\d{4}-\d{2}-\d{2}$ type: string basis: description: >- Use portfolio_value for any new portfolio notional, including a fund NAV found at the user's request. fund_total_nav is only for an explicit, user-declared fund-total-NAV statement. enum: - portfolio_value - fund_total_nav type: string currency: description: >- Ledger currency established by source or user edit evidence, or by verified Itoflow provider symbol metadata; never infer it from unverified symbol text, exchange, broker, country, or filename. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string source: description: Where the one stated portfolio value came from. enum: - user_declared - source_document type: string required: - amount - as_of_date - basis - currency - source type: object revision: description: >- Draft revision number; it increases each time the draft is reparsed or repaired. minimum: 0 type: integer schema_version: description: Portfolio upload draft schema version; currently v1. enum: - v1 type: string source_attachments: default: [] description: >- Compact references to the files or screenshots used to parse this draft. items: additionalProperties: false description: >- Compact reference to a source attachment used to parse the draft. properties: attachment_id: description: Stable chat attachment id when available. type: string filename: description: Original uploaded filename or screenshot label. maxLength: 240 minLength: 1 type: string media_type: description: Attachment MIME/media type when known. maxLength: 120 minLength: 1 type: string sha256: description: Hash of the source attachment when available. maxLength: 128 minLength: 8 type: string workspace_path: description: >- Workspace path for the attachment artifact when available. maxLength: 400 minLength: 1 type: string required: - filename type: object type: array source_broker: description: >- Broker or platform the user appears to keep this portfolio in; metadata only, never evidence for row currency or quote unit. enum: - trading212 - robinhood - zerodha - alpaca - ibkr - other type: string validation_issues: default: [] description: >- Draft-level validation issues not tied to one holding or cash row. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array required: - draft_id - execution_mode - holdings - portfolio_name - portfolio_type - revision - schema_version type: object draft_file: additionalProperties: false description: Optional draft.json file reference used for auditability. properties: path: description: >- Workspace-relative path to the validated draft JSON file. maxLength: 240 minLength: 1 type: string sha256: description: Hash of the draft JSON file when available. maxLength: 128 minLength: 8 type: string size_bytes: description: Draft JSON file size in bytes when available. minimum: 0 type: integer required: - path type: object output_id: description: Stable portfolio_import output id for idempotency. maxLength: 240 minLength: 1 type: string required: - draft - output_id type: object required: true responses: '200': content: application/json: schema: oneOf: - additionalProperties: false description: Successful portfolio import preflight response. properties: allocated_amount_usd: description: >- USD capital allocated from cash and holdings with a current USD valuation. If valuation_coverage is partial, this excludes unvalued holdings and is not the complete portfolio market value. minLength: 1 type: string approval_token: description: >- Signed token authorizing import of the currently validated draft. minLength: 1 type: string book_summary: additionalProperties: false description: >- Long, short, gross, and net exposure. Cash counts only in NAV. An unvalued holding makes its leg, gross value, net value, NAV and all weights null, with valuation_unavailable_reason. properties: gross_value: description: >- Sum of absolute holding values in USD: long value less short value; null when any holding has no current USD value. minLength: 1 type: - string - 'null' gross_weight: description: >- Gross value over NAV; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' long_value: description: >- Sum of long holding values in USD; null when a long holding has no current USD value. minLength: 1 type: - string - 'null' long_weight: description: >- Long value over NAV; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' nav: description: >- Cash plus signed holding values in USD; null when any holding has no current USD value. minLength: 1 type: - string - 'null' net_value: description: >- Sum of signed holding values in USD: long value plus short value; null when any holding has no current USD value. minLength: 1 type: - string - 'null' net_weight: description: >- Net value over NAV; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' short_value: description: >- Sum of short holding values in USD; zero or negative, or null when a short holding has no current USD value. minLength: 1 type: - string - 'null' short_weight: description: >- Short value over NAV, zero or negative; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' valuation_unavailable_reason: description: >- Why net asset value and weights are unknown when a holding has no current USD value. minLength: 1 type: string required: - long_value - short_value - gross_value - net_value - nav - long_weight - short_weight - gross_weight - net_weight type: object execution_mode: description: Execution mode that will be used by import. enum: - paper type: string holding_prices: description: >- Provider current prices resolved during preflight for display in the review UI. Inspect valuation_coverage and unvalued_holding_row_ids before treating allocated_amount_usd as a complete value. items: additionalProperties: false description: >- Provider current price attached to a holding during import preflight; this is display data, not user input. properties: currency: description: >- Ledger currency for the provider price after quote-unit normalization. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string price_date: description: >- Provider market-data date for this current price when available. maxLength: 40 minLength: 1 type: - string - 'null' price_unit: description: >- Quote denomination for unit_value as returned for review display. enum: - NATIVE - GBX - ZAC - ILA type: string row_id: description: Holding row id this provider price belongs to. maxLength: 80 minLength: 1 type: string symbol: description: >- Fully qualified Itoflow symbol this provider price belongs to. maxLength: 80 minLength: 1 type: string unit_scale: description: >- Quote-unit subdivision scale when price_unit is GBX, ZAC, or ILA. enum: - '0.01' type: string unit_value: description: >- Provider current market price per one share/unit in currency and price_unit terms. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string required: - currency - price_unit - row_id - symbol - unit_value type: object type: array imported_cash_count: description: Count of included cash rows accepted by preflight. minimum: 0 type: integer imported_holding_count: description: Count of included holding rows accepted by preflight. minimum: 0 type: integer normalized_draft: additionalProperties: false description: >- Provider-verified draft used to create the approval token, including exact symbol, currency, and quote-unit metadata resolved during preflight. properties: approved_at: anyOf: - format: date-time type: string - format: date-time type: string description: >- ISO timestamp set when the user approved this edited draft. cash: default: [] description: >- Optional parsed cash balances to import alongside holdings. items: additionalProperties: false description: >- One parsed cash balance row for the editable portfolio upload review. properties: amount: description: >- Cash amount in the row currency; negative for borrowed cash such as a margin loan. Never a security quantity or portfolio total unless explicitly a cash balance. pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: string currency: description: >- Ledger currency established by source or user edit evidence, or by verified Itoflow provider symbol metadata; never infer it from unverified symbol text, exchange, broker, country, or filename. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string included: default: true description: >- Whether this cash row should be imported if the user confirms. type: boolean issues: default: [] description: >- Cash-row parser or validation issues; error severity blocks confirmation. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: >- Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: >- Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array row_id: description: >- Stable cash row id used for edits, validation errors, and import diagnostics. maxLength: 80 minLength: 1 type: string source: description: >- Short source note for the cash row, such as filename, screenshot area, or sheet name. maxLength: 240 type: string required: - amount - row_id type: object type: array draft_id: description: >- Stable id for this parsed portfolio draft across review revisions. maxLength: 120 minLength: 1 type: string execution_mode: description: >- Always paper for chat portfolio uploads; this import cannot create a live portfolio. enum: - paper type: string holdings: description: >- Parsed holding rows for user review and possible import. items: additionalProperties: false description: >- One parsed holding row for the editable portfolio upload review. properties: cost_basis: description: >- Optional average entry price per one share/unit in currency and price_unit terms; omit when unknown and never use 0 as a placeholder; never copy total cost, total invested, or current value into this field. A deterministic per-unit value reconciled from quantity, market value, signed unrealized P&L, explicit currency evidence, and available current-price evidence is allowed when the derivation is recorded as a row warning. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string currency: description: >- Ledger currency established by source or user edit evidence, or by verified Itoflow provider symbol metadata; never infer it from unverified symbol text, exchange, broker, country, or filename. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string included: default: true description: >- Whether this holding row should be imported if the user confirms. type: boolean issues: default: [] description: >- Row-scoped parser or validation issues; error severity blocks confirmation. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: >- Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: >- Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array price_unit: default: NATIVE description: >- Quote denomination for unit_value and cost_basis; use NATIVE unless the source or selected Itoflow symbol metadata explicitly quotes GBX, ZAC, or ILA. enum: - NATIVE - GBX - ZAC - ILA type: string quantity: description: >- Signed number of shares or units held: positive for a long, negative for a short. Never market value, allocation weight, total cost, or cash. pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: string row_id: description: >- Stable row id used for edits, validation errors, and import diagnostics. maxLength: 80 minLength: 1 type: string side: description: >- Optional position side copied from a side column: long or L, short or S, in any case. A short side turns a positive quantity negative; omit side when the quantity already carries its sign. pattern: >- ^(?:[Ll][Oo][Nn][Gg]|[Ll]|[Ss][Hh][Oo][Rr][Tt]|[Ss])$ type: string source: description: >- Short source note for the row, such as filename, screenshot area, or sheet name. maxLength: 240 type: string symbol: description: >- Fully qualified holding symbol in SYMBOL.EXCHANGE format, matching symbol_resolution.symbol after lookup. maxLength: 80 minLength: 1 type: string symbol_resolution: additionalProperties: false description: >- Selected Itoflow symbol lookup result for a holding; this is not free text. properties: code: description: >- Provider ticker code from the selected Itoflow symbol result. maxLength: 40 minLength: 1 type: string currency: description: >- Currency or quote-unit alias returned by the selected Itoflow symbol result. pattern: ^(?:[A-Z]{3}|GBp)$ type: - string - 'null' exchange: description: >- Exchange code from the selected Itoflow symbol result. maxLength: 40 minLength: 1 type: string name: description: >- Instrument name from the selected Itoflow symbol result. maxLength: 240 minLength: 1 type: string symbol: description: >- Fully qualified Itoflow symbol selected from lookup, e.g. AAPL.US. maxLength: 80 minLength: 1 type: string type: description: >- Instrument type from the selected Itoflow symbol result when known. maxLength: 120 type: - string - 'null' required: - code - exchange - name - symbol type: object unit_scale: description: >- Required only for supported quote subdivisions GBX, ZAC, or ILA; omit for NATIVE price units. enum: - '0.01' type: string unit_value: description: >- Optional parsed current market price per one share/unit in currency and price_unit terms; omit when unknown. Import validation ignores this field and resolves provider current prices for display when available; never total row value, market value, account value, invested value, or position value. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string required: - quantity - row_id - symbol type: object maxItems: 3000 type: array parser_warnings: default: [] description: >- Draft-level parsing warnings from ambiguous or incomplete source evidence. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array portfolio_name: description: >- User-editable name for the managed paper portfolio to create. maxLength: 100 minLength: 1 type: string portfolio_type: description: >- Always managed for chat portfolio uploads; this import cannot create a reference portfolio. enum: - managed type: string portfolio_value: additionalProperties: false description: >- Optional user/source value to reconcile with quantity-bearing holdings. Omit when the current provider-priced mark is the only known value. properties: amount: description: >- Decimal string without commas or currency symbols. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string as_of_date: description: >- Date of the user or source portfolio value, not the import timestamp. pattern: ^\d{4}-\d{2}-\d{2}$ type: string basis: description: >- Use portfolio_value for any new portfolio notional, including a fund NAV found at the user's request. fund_total_nav is only for an explicit, user-declared fund-total-NAV statement. enum: - portfolio_value - fund_total_nav type: string currency: description: >- Ledger currency established by source or user edit evidence, or by verified Itoflow provider symbol metadata; never infer it from unverified symbol text, exchange, broker, country, or filename. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string source: description: >- Where the one stated portfolio value came from. enum: - user_declared - source_document type: string required: - amount - as_of_date - basis - currency - source type: object revision: description: >- Draft revision number; it increases each time the draft is reparsed or repaired. minimum: 0 type: integer schema_version: description: >- Portfolio upload draft schema version; currently v1. enum: - v1 type: string source_attachments: default: [] description: >- Compact references to the files or screenshots used to parse this draft. items: additionalProperties: false description: >- Compact reference to a source attachment used to parse the draft. properties: attachment_id: description: Stable chat attachment id when available. type: string filename: description: >- Original uploaded filename or screenshot label. maxLength: 240 minLength: 1 type: string media_type: description: Attachment MIME/media type when known. maxLength: 120 minLength: 1 type: string sha256: description: >- Hash of the source attachment when available. maxLength: 128 minLength: 8 type: string workspace_path: description: >- Workspace path for the attachment artifact when available. maxLength: 400 minLength: 1 type: string required: - filename type: object type: array source_broker: description: >- Broker or platform the user appears to keep this portfolio in; metadata only, never evidence for row currency or quote unit. enum: - trading212 - robinhood - zerodha - alpaca - ibkr - other type: string validation_issues: default: [] description: >- Draft-level validation issues not tied to one holding or cash row. items: additionalProperties: false description: >- Typed validation or parser issue attached to the portfolio draft. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: default: error description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message type: object type: array required: - draft_id - execution_mode - holdings - portfolio_name - portfolio_type - revision - schema_version type: object ok: description: True when preflight succeeded. enum: - true type: boolean portfolio_type: description: Portfolio type that will be created by import. enum: - managed type: string portfolio_value: additionalProperties: false description: >- Reviewed value provenance and its difference from the current provider mark, when comparable. properties: amount_usd: description: Reviewed portfolio value in USD. type: string as_of_date: description: Date of the reviewed value, when known. type: - string - 'null' basis: description: Role of the reviewed value. enum: - portfolio_value - fund_total_nav type: string current_mark_as_of_date: description: Date of the provider-priced mark, when known. type: - string - 'null' current_mark_usd: description: >- Current provider-priced mark in USD, when available. type: - string - 'null' difference_usd: description: >- Reviewed value less the current provider mark in USD, when comparable. type: - string - 'null' source: description: Provenance of the reviewed value. enum: - provider_derived - user_declared - source_document type: string required: - amount_usd - as_of_date - basis - current_mark_usd - current_mark_as_of_date - difference_usd - source type: object row_warnings: description: >- Per-holding valuation warnings with row_id. Price warnings use field price: price_not_fetched means the vendor did not answer; no_recent_close means no usable close in the last 14 days. holding_fx_unavailable uses field currency and names the missing exchange rate to USD. Warnings do not block confirmation. items: additionalProperties: false description: >- Normalized validation or parser issue returned by portfolio import APIs. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message - severity type: object type: array source_broker: description: >- Broker metadata accepted from the draft, or null when absent. enum: - trading212 - robinhood - zerodha - alpaca - ibkr - other - null type: - string - 'null' unvalued_holding_row_ids: description: >- Included holding row ids without a current USD value. Review these rows before approving a partial valuation. Empty for complete or not_rechecked coverage. items: type: string type: array valuation_coverage: description: >- complete means every included holding has a current USD value; partial means some included holdings are unvalued; not_rechecked is an idempotent preflight for an already imported portfolio. enum: - complete - partial - not_rechecked type: string required: - approval_token - allocated_amount_usd - valuation_coverage - unvalued_holding_row_ids - holding_prices - execution_mode - imported_cash_count - imported_holding_count - ok - portfolio_type - source_broker type: object - additionalProperties: false description: >- Failed portfolio import preflight with prices and exposure for valid rows when available. properties: allocated_amount_usd: description: USD capital requested by the draft when calculable. minLength: 1 type: string available: description: >- Available value for balance or capacity failures when available. minLength: 1 type: string book_summary: additionalProperties: false description: >- Long, short, gross, and net exposure. Cash counts only in NAV. An unvalued holding makes its leg, gross value, net value, NAV and all weights null, with valuation_unavailable_reason. properties: gross_value: description: >- Sum of absolute holding values in USD: long value less short value; null when any holding has no current USD value. minLength: 1 type: - string - 'null' gross_weight: description: >- Gross value over NAV; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' long_value: description: >- Sum of long holding values in USD; null when a long holding has no current USD value. minLength: 1 type: - string - 'null' long_weight: description: >- Long value over NAV; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' nav: description: >- Cash plus signed holding values in USD; null when any holding has no current USD value. minLength: 1 type: - string - 'null' net_value: description: >- Sum of signed holding values in USD: long value plus short value; null when any holding has no current USD value. minLength: 1 type: - string - 'null' net_weight: description: >- Net value over NAV; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' short_value: description: >- Sum of short holding values in USD; zero or negative, or null when a short holding has no current USD value. minLength: 1 type: - string - 'null' short_weight: description: >- Short value over NAV, zero or negative; null when NAV is unknown or not above zero. minLength: 1 type: - string - 'null' valuation_unavailable_reason: description: >- Why net asset value and weights are unknown when a holding has no current USD value. minLength: 1 type: string required: - long_value - short_value - gross_value - net_value - nav - long_weight - short_weight - gross_weight - net_weight type: object error: description: Stable machine-readable import error code. maxLength: 120 minLength: 1 type: string holding_prices: description: >- Prices for valid rows while other rows have blocking errors. These prices do not authorize import. items: additionalProperties: false description: >- Provider current price attached to a holding during import preflight; this is display data, not user input. properties: currency: description: >- Ledger currency for the provider price after quote-unit normalization. enum: - USD - EUR - GBP - ZAR - ILS - JPY - CAD - AUD - CHF - INR - HKD - SEK - NOK - DKK - PLN - SGD - KRW - TWD - CNY - SAR - TRY - QAR - AED - ISK - NZD type: string price_date: description: >- Provider market-data date for this current price when available. maxLength: 40 minLength: 1 type: - string - 'null' price_unit: description: >- Quote denomination for unit_value as returned for review display. enum: - NATIVE - GBX - ZAC - ILA type: string row_id: description: Holding row id this provider price belongs to. maxLength: 80 minLength: 1 type: string symbol: description: >- Fully qualified Itoflow symbol this provider price belongs to. maxLength: 80 minLength: 1 type: string unit_scale: description: >- Quote-unit subdivision scale when price_unit is GBX, ZAC, or ILA. enum: - '0.01' type: string unit_value: description: >- Provider current market price per one share/unit in currency and price_unit terms. pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ type: string required: - currency - price_unit - row_id - symbol - unit_value type: object type: array message: description: >- Short user-facing explanation of why validation or import failed. maxLength: 500 minLength: 1 type: string ok: description: False when validation or import failed. enum: - false type: boolean requested: description: >- Requested value for balance or capacity failures when available. minLength: 1 type: string row_errors: description: >- Typed row-level errors, for showing beside fields and for fixing rows. items: additionalProperties: false description: >- Normalized validation or parser issue returned by portfolio import APIs. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message - severity type: object type: array row_warnings: description: >- Per-holding valuation warnings with row_id. Price warnings use field price: price_not_fetched means the vendor did not answer; no_recent_close means no usable close in the last 14 days. holding_fx_unavailable uses field currency and names the missing exchange rate to USD. Warnings do not block confirmation. items: additionalProperties: false description: >- Normalized validation or parser issue returned by portfolio import APIs. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message - severity type: object type: array valuation_scope: description: >- On a failed review, book_summary covers only rows that passed validation; it is not exposure for the full book. enum: - valid_rows type: string required: - error - message - ok - row_errors type: object description: >- Portfolio import validation result. An unvalued holding makes book_summary NAV and all weights null, with valuation_unavailable_reason. '401': content: application/json: schema: $ref: '#/components/schemas/Error' description: Authentication required '403': content: application/json: schema: $ref: '#/components/schemas/Error' description: Forbidden '500': content: application/json: schema: additionalProperties: false description: Portfolio import validation or import failure response. properties: allocated_amount_usd: description: USD capital requested by the draft when calculable. minLength: 1 type: string available: description: >- Available value for balance or capacity failures when available. minLength: 1 type: string error: description: Stable machine-readable import error code. maxLength: 120 minLength: 1 type: string message: description: >- Short user-facing explanation of why validation or import failed. maxLength: 500 minLength: 1 type: string ok: description: False when validation or import failed. enum: - false type: boolean requested: description: >- Requested value for balance or capacity failures when available. minLength: 1 type: string row_errors: description: >- Typed row-level errors, for showing beside fields and for fixing rows. items: additionalProperties: false description: >- Normalized validation or parser issue returned by portfolio import APIs. properties: code: description: Stable machine-readable issue code. maxLength: 80 minLength: 1 type: string field: description: >- Draft field path or row control this issue belongs to when known. maxLength: 120 minLength: 1 type: string message: description: Short user-facing explanation of the issue. maxLength: 500 minLength: 1 type: string row_id: description: >- Row id this issue belongs to when the issue is row-scoped. maxLength: 80 minLength: 1 type: string severity: description: Issue severity; error blocks confirmation. enum: - info - warning - error type: string required: - code - message - severity type: object type: array required: - error - message - ok - row_errors type: object description: Server error security: - bearerAuth: [] components: schemas: Error: properties: available: description: Optional available amount or value type: string billing_action: $ref: '#/components/schemas/BillingAction' code: description: Machine-readable error code type: string currentVersion: description: Current server-side version, when relevant type: number details: description: Optional structured error details error: description: Error type or code type: string expectedVersion: description: Client-provided expected version, when relevant type: number message: description: Human-readable error message type: string requested: description: Optional requested amount or value type: string usage: description: Optional usage metadata for limit errors required: - error type: object BillingAction: description: Action that resolves a billing-related rejection properties: href: type: string kind: enum: - upgrade - payment_method - spending_cap - billing type: string label: type: string required: - href - label - kind type: object securitySchemes: bearerAuth: bearerFormat: JWT description: Itoflow access token issued for the Itoflow API. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.