> ## 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. # Commit an approved paper portfolio import > Commit the normalized draft returned by preflight only after explicit user approval. Set draft.approved_at, use the reviewed output id with an :approved suffix, and pass the current approval token. If pricing or any material input changed, revalidate and review again. Operation ID: post__portfolios_import. ## OpenAPI ````yaml /openapi/itoflow-public.openapi.json post /portfolios/import 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: post: tags: - Portfolios summary: Commit an approved paper portfolio import description: >- Commit the normalized draft returned by preflight only after explicit user approval. Set draft.approved_at, use the reviewed output id with an :approved suffix, and pass the current approval token. If pricing or any material input changed, revalidate and review again. Operation ID: post__portfolios_import. operationId: post__portfolios_import requestBody: content: application/json: schema: additionalProperties: false description: >- Commit the exact normalized draft returned by preflight after explicit user approval. Add draft.approved_at, use an output_id ending :approved, and pass the current approval_token. Revalidate and obtain renewed approval after a material change. properties: approval_token: description: >- Current approval_token returned by preflight for the exact normalized draft and allocated amount. maxLength: 4000 minLength: 1 type: string draft: additionalProperties: false properties: approved_at: anyOf: - format: date-time type: string - format: date-time type: string description: >- ISO timestamp set only after the user explicitly approves the complete reviewed 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 - approved_at 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 reviewed output id ending in :approved. Preserve the reviewed id prefix for idempotency. maxLength: 240 minLength: 1 pattern: ':approved$' type: string required: - approval_token - draft - output_id type: object required: true responses: '200': content: application/json: schema: anyOf: - additionalProperties: false description: Successful managed paper portfolio import response. properties: allocated_amount_usd: description: >- USD capital allocated to the imported managed paper portfolio. minLength: 1 type: string execution_mode: description: Execution mode of the created portfolio. enum: - paper type: string idempotent: description: >- True when this response came from an idempotent retry of an existing import. type: boolean imported_cash_count: description: Count of cash rows imported. minimum: 0 type: integer imported_holding_count: description: Count of holding rows imported. minimum: 0 type: integer ok: description: True when import succeeded. enum: - true type: boolean portfolio_id: description: Id of the created managed paper portfolio. minLength: 1 type: string portfolio_type: description: Portfolio type of the created portfolio. enum: - managed type: string portfolio_url: description: App URL path for the created portfolio. minLength: 1 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 presentation_hint: description: >- Hint about what is attached to the portfolio, based on verified state. A fresh import has nothing attached and keeps any watch-or-manage intent already supplied; an idempotent retry may instead report an existing monitor or strategy, or say the state could not be verified. A failed lookup does not mean nothing is attached. minLength: 1 type: string 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 stored with the created portfolio, or null when absent. enum: - trading212 - robinhood - zerodha - alpaca - ibkr - other - null type: - string - 'null' strategy_id: description: >- Id of a controlling strategy already linked to this portfolio, when present. Fresh import does not create a strategy; this is set only on an idempotent retry of an older import that already has one. minLength: 1 type: string strategy_name: description: >- Name of the already-linked controlling strategy, when present. minLength: 1 type: string strategy_url: description: >- App URL path for the already-linked controlling strategy, when present. minLength: 1 type: string required: - ok - portfolio_id - portfolio_url type: object - 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: Idempotent portfolio import result '201': content: application/json: schema: additionalProperties: false description: Successful managed paper portfolio import response. properties: allocated_amount_usd: description: >- USD capital allocated to the imported managed paper portfolio. minLength: 1 type: string execution_mode: description: Execution mode of the created portfolio. enum: - paper type: string idempotent: description: >- True when this response came from an idempotent retry of an existing import. type: boolean imported_cash_count: description: Count of cash rows imported. minimum: 0 type: integer imported_holding_count: description: Count of holding rows imported. minimum: 0 type: integer ok: description: True when import succeeded. enum: - true type: boolean portfolio_id: description: Id of the created managed paper portfolio. minLength: 1 type: string portfolio_type: description: Portfolio type of the created portfolio. enum: - managed type: string portfolio_url: description: App URL path for the created portfolio. minLength: 1 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 presentation_hint: description: >- Hint about what is attached to the portfolio, based on verified state. A fresh import has nothing attached and keeps any watch-or-manage intent already supplied; an idempotent retry may instead report an existing monitor or strategy, or say the state could not be verified. A failed lookup does not mean nothing is attached. minLength: 1 type: string 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 stored with the created portfolio, or null when absent. enum: - trading212 - robinhood - zerodha - alpaca - ibkr - other - null type: - string - 'null' strategy_id: description: >- Id of a controlling strategy already linked to this portfolio, when present. Fresh import does not create a strategy; this is set only on an idempotent retry of an older import that already has one. minLength: 1 type: string strategy_name: description: >- Name of the already-linked controlling strategy, when present. minLength: 1 type: string strategy_url: description: >- App URL path for the already-linked controlling strategy, when present. minLength: 1 type: string required: - ok - portfolio_id - portfolio_url type: object description: Portfolio imported '400': 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: Portfolio import rejected '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.