--- title: "Append an action, value, correction, closure, or reversal to one financial impact." method: POST path: "/v1/impacts/record" --- # Append an action, value, correction, closure, or reversal to one financial impact. `POST /v1/impacts/record` ## Request - Base URL: `https://api.candor.money` - URL: `https://api.candor.money/v1/impacts/record` - Auth: HTTP bearer Append an action, value, correction, closure, or reversal to one financial impact. ## Headers - `Idempotency-Key` string, required ## Request body - FinancialImpactRecordRequest - `impact_id` string, required: The stable impact returned at discovery. Reuse it so discovery, action, outcome, and correction remain one history. - `event` union, required: Typed event to append to the existing impact history. - union - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[], required: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'action_taken', required: Record a concrete step taken for this impact. - `action_summary` string, required: What the agent or user actually did. - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[]: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string, required: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'action_taken', required: Record a concrete step taken for this impact. - `action_summary` string, required: What the agent or user actually did. - union - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[], required: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'value_recorded', required: Record an observed or realized value. - `state` 'outcome_observed' | 'realized', required: Whether the value is observed or has actually landed. - `value_basis` 'observed' | 'agent_attested' | 'user_confirmed' | 'evidence_verified', required: Who or what supports the value. Agent attestation is accepted and remains visibly distinct from independent verification. - `value` union, required: Exact value without mixed units. Gross benefit and implementation cost remain separate; one-time, bounded, recurring, and time value never collapse into one headline number. - object - `kind` 'one_time', required: Treat this as one-time money. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - object - `kind` 'bounded_total', required: Treat this as a total over one explicit window. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `window_start` string, date-time, required: Inclusive start of the value window. - `window_end` string, date-time, required: Inclusive end of the value window. - object - `kind` 'recurring_rate', required: Treat this as a recurring money rate. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `interval` 'monthly' | 'annual', required: Cadence of the recurring value. - object - `kind` 'time', required: Treat this as time returned to the user. - `duration` string, required: Positive exact decimal duration. - `unit` 'minutes' | 'hours', required: Unit of the returned time. - `supersedes_event_id` string: The active value event this corrects. Its history remains, but it leaves current aggregates. - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[]: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string, required: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'value_recorded', required: Record an observed or realized value. - `state` 'outcome_observed' | 'realized', required: Whether the value is observed or has actually landed. - `value_basis` 'observed' | 'agent_attested' | 'user_confirmed' | 'evidence_verified', required: Who or what supports the value. Agent attestation is accepted and remains visibly distinct from independent verification. - `value` union, required: Exact value without mixed units. Gross benefit and implementation cost remain separate; one-time, bounded, recurring, and time value never collapse into one headline number. - object - `kind` 'one_time', required: Treat this as one-time money. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - object - `kind` 'bounded_total', required: Treat this as a total over one explicit window. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `window_start` string, date-time, required: Inclusive start of the value window. - `window_end` string, date-time, required: Inclusive end of the value window. - object - `kind` 'recurring_rate', required: Treat this as a recurring money rate. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `interval` 'monthly' | 'annual', required: Cadence of the recurring value. - object - `kind` 'time', required: Treat this as time returned to the user. - `duration` string, required: Positive exact decimal duration. - `unit` 'minutes' | 'hours', required: Unit of the returned time. - `supersedes_event_id` string: The active value event this corrects. Its history remains, but it leaves current aggregates. - union - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[], required: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[], required: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[]: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string, required: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[]: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string, required: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - union - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[], required: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'potential_revised', required: Replace or remove the active potential value. - `potential_value` union, required: Exact value without mixed units. Gross benefit and implementation cost remain separate; one-time, bounded, recurring, and time value never collapse into one headline number. - object - `kind` 'one_time', required: Treat this as one-time money. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - object - `kind` 'bounded_total', required: Treat this as a total over one explicit window. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `window_start` string, date-time, required: Inclusive start of the value window. - `window_end` string, date-time, required: Inclusive end of the value window. - object - `kind` 'recurring_rate', required: Treat this as a recurring money rate. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `interval` 'monthly' | 'annual', required: Cadence of the recurring value. - object - `kind` 'time', required: Treat this as time returned to the user. - `duration` string, required: Positive exact decimal duration. - `unit` 'minutes' | 'hours', required: Unit of the returned time. - `supersedes_event_id` string: The exact active potential-value event_id returned by the impact view. Required when replacing or removing an active potential; omit only when adding the first potential value. - object - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[]: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - … - object - … - object - … - object - … - object - … - `context_note_id` string, required: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'potential_revised', required: Replace or remove the active potential value. - `potential_value` union, required: Exact value without mixed units. Gross benefit and implementation cost remain separate; one-time, bounded, recurring, and time value never collapse into one headline number. - object - `kind` 'one_time', required: Treat this as one-time money. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - object - `kind` 'bounded_total', required: Treat this as a total over one explicit window. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `window_start` string, date-time, required: Inclusive start of the value window. - `window_end` string, date-time, required: Inclusive end of the value window. - object - `kind` 'recurring_rate', required: Treat this as a recurring money rate. - `gross_benefit` union, required: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `implementation_cost` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - … - `interval` 'monthly' | 'annual', required: Cadence of the recurring value. - object - `kind` 'time', required: Treat this as time returned to the user. - `duration` string, required: Positive exact decimal duration. - `unit` 'minutes' | 'hours', required: Unit of the returned time. - `supersedes_event_id` string: The exact active potential-value event_id returned by the impact view. Required when replacing or removing an active potential; omit only when adding the first potential value. - FinancialImpactClosedEvent - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[]: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - `type` 'transaction', required: Reference a transaction. - `id` string, required: Transaction id supporting the impact. - object - `type` 'account', required: Reference a canonical account identity. - `id` string, required: Account identity id supporting the impact. - object - `type` 'recurring_item', required: Reference a recurring financial item. - `id` string, required: Recurring item id supporting the impact. - object - `type` 'goal', required: Reference a first-class financial goal. - `id` string, required: Goal id supporting the impact. - object - `type` 'action', required: Reference a prior Candor action that records why it happened. - `id` string, required: Action id supporting the impact. - `context_note_id` string: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'closed_without_value', required: Close work that ended without financial value. - `reason_summary` string, required: Why this ended without realized value. - FinancialImpactRevertedEvent - `occurred_at` string, date-time: When this happened. Omit only when it happened now. - `basis_refs` FinancialImpactBasisRef[]: Typed records supporting this statement. Omit only when a linked context note carries the reconstructable basis instead. - union: A typed record supporting the impact. The id is resolved inside the same vault; an arbitrary resource string is never accepted. - object - `type` 'transaction', required: Reference a transaction. - `id` string, required: Transaction id supporting the impact. - object - `type` 'account', required: Reference a canonical account identity. - `id` string, required: Account identity id supporting the impact. - object - `type` 'recurring_item', required: Reference a recurring financial item. - `id` string, required: Recurring item id supporting the impact. - object - `type` 'goal', required: Reference a first-class financial goal. - `id` string, required: Goal id supporting the impact. - object - `type` 'action', required: Reference a prior Candor action that records why it happened. - `id` string, required: Action id supporting the impact. - `context_note_id` string: A note containing calculation detail, caveats, or external context. Note text remains context rather than verified evidence. - `type` 'reverted', required: Reverse an active observed or realized value. - `reason_summary` string, required: Why the observed or realized value is no longer valid. - `reverses_event_id` string, required: The active observed- or realized-value event removed from current aggregates. ## Response `200` Updated financial impact envelope. - 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)