---
title: "Manage Account"
method: POST
path: "/api/facade/manage_account"
tags: ["facade"]
---

# Manage Account

`POST /api/facade/manage_account`

## Request

- Base URL: `https://api.vruum.ai`
- URL: `https://api.vruum.ai/api/facade/manage_account`
- Auth: `HTTPBearer` (a scheme the document does not define)

Maintain account state and impact history — the consolidated account writer.

Actions:
- objective_expansion: inspect current customers for the objective offer and
  save reviewed expansion candidates (id = objective UUID). Preparation
  creates reviewable work and does not contact anyone.
- discovery_create: start discovery for an engagement with no current record
  (no id; DiscoveryCreateRequest). Read customer_impact first. Provide journey_id,
  the known situation and/or pain, and a reason. The receipt id is the new claim_id.
  Facts remain unconfirmed; missing SPICED points stay unknown. This does not
  define a delivery promise, assign a priority or advance a deal. Existing records
  must use discovery_fact. Retries use the same request_key.
- discovery_fact: edit one canonical SPICED point (DiscoveryFactRequest).
  Fetch customer_impact first. Copy the element's edit_values into values,
  edit those values, and provide the operator's reason. Pass discovery.claim_id,
  value_hash, edit_id, and review.id as claim_id, expected_value_hash,
  expected_edit_id, and expected_review_id. Null clears a field. Decision
  edits change criteria/process only; use buying_roles for engagement roles.
  This preserves frozen delivery terms, timeline commitments and results.
  Edited facts require a fresh customer review; recording is not confirmation.
- discovery_review: review one exact SPICED element (no id; DiscoveryReviewRequest).
  Include the element edit_id as expected_edit_id.
  Read account impact first. Use discovery.claim_id and the element's review.id
  as expected_review_id; pass the element's value_hash as expected_value_hash.
  Confirm or contradict with a reviewed original customer
  email/transcript quotation and current source IDs. Explicitly attribute account
  sources to the engagement when necessary. Withdraw the latest assertion with
  its predecessor and reason, without new sources. Missing facts cannot be
  confirmed; a new claim revision or changed proof needs review. No deal stage,
  claim confidence, impact verification or measurement changes occur.
- renewal_review: assigned-owner acceptance, dismissal or reported completion
  of a RenewalDecision (no id). Read customer_impact.renewal.work first for
  action_id and expected_version; pass account_id, decision and a review note.
  Completion records work only: it never sends, verifies impact or renews terms.
- customer_growth_record: record an internal growth proposal (no id;
  CustomerGrowthRecord). Read customer_impact.customer_growth first. Pass
  account_id, expected_fingerprint and draft as the current account owner.
  Proposals cover advocacy, referral, nurture or retirement and require
  current sources. Recording never sends, publishes or changes account state.
- customer_growth_review: review sourced growth work (no id;
  CustomerGrowthDecision). Read customer_impact.customer_growth first. Pass
  account_id, action_id, expected_version, expected_fingerprint, decision
  and note. Permission decisions require the exact customer source and
  separate permission scope. Completion records internal work only; it never
  sends, publishes, enrolls, retires an account or changes billing.
- kickoff_plan: save a KickoffPlanRequest (no id). Read customer_impact first
  for kickoff_plan.expected_fingerprint. Save a draft revision or quote a
  native customer statement about the exact plan reference. Never sends.
- critical_event_step: record a reviewed CriticalEventStepRequest (no id).
  Fetch customer_impact first. Pin timeline_evidence_id, action_id,
  expected_version and expected_decision_id for that decision. accept is
  assigned-owner approval of manual work; confirm requires original customer
  words and a reviewed commitment date; complete requires current evidence,
  accepted work and completed prerequisites. Corrections append; retract
  withdraws confirmation/completion proof without undoing action history.
  No sending, customer-impact verification or result credit occurs.
- critical_event: save a human-reviewed CriticalEventRequest (no id). Fetch
  customer_impact first. Pin its current promise, criterion and occurrence;
  use critical_event.evidence_id as expected_evidence_id. Name the customer's
  consequence and sources. Ordered steps have distinct keys, calendar-day
  durations, optional workspace owners and earliest starts; dependencies name
  earlier keys. Saving proposes human-only Actions, never approves execution,
  confirms customer commitments, or changes the promised deadline. Revisions
  replace proposed steps only; progressed work must retain its commitments.
- buying_roles: revise sourced buying roles for one engagement (no id;
  JourneyBuyingRolesRequest). Read fetch type=customer_impact first; use its
  buying_roles.evidence_id as expected_evidence_id. Replace the full members
  list, naming each person's role, reason and source_evidence_ids. An empty
  list explicitly clears all assignments. Preserve unknowns; job titles and
  deal stakeholder membership do not prove authority. Show the exact revision
  and obtain human approval. attribute_sources_to_journey=true explicitly
  assigns account evidence to this engagement. This is an operator assessment,
  not customer confirmation, deal qualification, or verified impact.
- journey_measurement_fact: record/correct/retract a sourced operator fact for
  an approved journey observation (no id; JourneyMeasurementFactRequest).
  Pin run_action_id, journey_id and independent exact-journey source_evidence_ids.
  checkpoint_balance describes the balance at the approved horizon;
  terminal_loss records its event time; impact_followup attests continuous
  observation with no qualifying impact from commitment through observed_at
  for the pinned promise. Requires explicit reviewed_source_records confirmation
  and an owner/operator. It does not certify complete external source coverage.
- customer_journey: record one sourced engagement (no id; payload is
  CustomerJourneyCreate: account_id, offer_id, kind, source_key,
  source_evidence_id and optional originating deal / trial relationship).
  Read fetch type=customer_impact id=account UUID first. Account UI: Impact tab.
- impact_promise: record/revise a sourced promise (no id; ImpactPromiseRequest).
  Freeze the journey, next promise_revision, criteria, owner and verifier policy.
  Supply expected_claim_id from the workspace. Preserve existing SPICED context.
- impact_report: report/correct/retract one criterion occurrence (no id;
  ImpactObservationRequest). Use the exact claim_id and current predecessor.
  attribute_sources_to_journey=true explicitly attributes matching account
  evidence to THIS result; it never rewrites the original source. Show this
  assignment to the user. Customer confirmation needs a matching inbound
  source, person and quotation. A model's assertion is not confirmation.
- impact_verify: verify the exact saved observation (no id;
  ImpactVerificationRequest). Obtain the user's explicit verification decision;
  recording a report is not permission to verify it. Current tenant membership,
  frozen verifier policy and source validity are rechecked by the same REST path.
  No action changes canonical First Impact/Recurring Impact metrics yet.
- task: create a follow-up task on the account (id = the account's
  company UUID; `payload` as for manage_person task).
- note: add a note to the account's record (id = the account's company
  UUID; `payload` = {body}). The response's note id and updated_at
  identify the note for a later edit.
- parent: set or clear corporate ownership (id=child company UUID).
  payload={parent_company_id: UUID|null, expected_parent_company_id: UUID|null,
  source:{url,title?,observed_at}}. Read fetch company_family first. A public
  source is required even when clearing. Native owner or operator only.
  Does not merge companies, inherit research, or add family members to CRM.
- list: create, rename, archive, or unarchive an account list. No id;
  payload={action, list_id? (required except create), name? (create/rename), description?}.
- list_members: add/remove tenant accounts in a list. No id;
  payload={action: add|remove, list_id, company_ids: [UUID, ...]} (1–200).
  Lists never change objectives or start outreach.
- state: update an account's lifecycle state (id = the account's
  company_id; `payload` = {renewal_at?, notes?, service_model?,
  scoped_labor_minutes_per_month?}. The lifecycle stage is NOT settable:
  it is a projection over recorded facts — a won deal (committed), the
  first post-commit impact event (onboarded), recurring impact
  (adopting; expansion_ready when no deal is open), sixty days without
  impact (dormant), a recorded `churn` event or a cancelled bound
  subscription (churned). Record the fact with record_impact or a deal
  outcome and the stage follows; the state read carries `lifecycle`
  with the basis and the facts).
  service_model (managed | self_serve_support | design_partner) and the scoped
  labor limit are the VRU-864 delivery-economics settings.
- record_impact: log a value-delivered impact event on an account
  (id = company_id; `payload` = {practice, event_type, person_id?,
  value_delivered_numeric?, value_delivered_unit?, source_type?,
  source_id?, occurred_at?, summary?, metadata?}).
- delete_impact: permanently remove an impact event (id = the impact
  EVENT/activity id, not the account). DESTRUCTIVE.
- adopt_directory: add a shared canonical company to this tenant's CRM
  (id = directory company UUID; no payload). The global company remains
  shared and cannot be edited unless the tenant separately owns it.
- record_labor: log labor done OUTSIDE this harness — calls,
  meetings, email, work in other tools (no id; `payload` = {entries:
  [{company_id?, service_model, work_type, minutes, source_ref?,
  note?}], work_date?, source? (operator_manual, the default |
  harness_telemetry)}). Do NOT log this session's own time: the server
  measures every harness MCP session from its tool calls
  automatically, so logging it here counts the minutes twice
  (source=harness_telemetry from an MCP call is refused). Idempotent
  per entry on source_ref (a source_ref reused with different content
  is refused — use one per piece of work; the 'mcp_span:' prefix is
  reserved for the server's own telemetry). operator_manual entries
  are confirmed at insert. The batch is write-safe: per-entry errors
  are reported in `errors`, never silently half-applied. Service model
  self_serve_support marks founder repair on a self-serve account —
  never blend it into managed. Work types: onboarding, campaign_ops,
  reply_handling, meeting, content, research, repair, support,
  expansion, admin.
- confirm_labor: the daily one-line confirmation of YOUR day (no id;
  `payload` = {work_date, entries?, confirm_telemetry?}). entries
  REPLACE your day for their account outright (every prior active row
  of yours there, of any source, is superseded, so corrected minutes
  win; a colleague's rows stay); confirm_telemetry=true stamps your
  own remaining unconfirmed telemetry as-is, never a colleague's.
  Refreshes each touched account's labor-scope claim in the ledger
  (failures reported in claim_failures). Read the economics with fetch
  type='unit_economics'.

Bulk: id arrays loop with per-item status (partial failure reported per
item, never silent; max 100). Every action checks its payload keys
against the route's own model first: an unknown key is a 422 that names
it and lists the fields the action takes. Values are validated by the
underlying route's schema.

## Request body

- WriterRequest: Uniform request body for every facade writer.
  - `action` string, required: The operation to perform — see the tool description for the action vocabulary and each action's id/payload semantics.
  - `id` union: Target entity id, or an ARRAY of ids to apply the same action+payload to each (max 100; see the tool description for which entity the id names per action).
    - string
    - string[]
  - `payload` object, nullable: Action-specific fields, validated by the underlying route's own schema (a bad field 422s with that route's precise errors). See the tool description per action.
  - `items` object[], nullable: For create-like actions only: an array of per-item payloads processed in order with per-item results (max 100). Mutually exclusive with `id` and `payload`.

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

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