---
title: "Manage History Import"
method: POST
path: "/api/facade/manage_history_import"
tags: ["facade"]
---

# Manage History Import

`POST /api/facade/manage_history_import`

## Request

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

Import past conversations, optionally discovering relevant CRM relationships.

The web equivalent is People → Import → Past conversations. Owners and
operators import any connected account; a member imports only a Gmail or
Outlook mailbox they connected, without discover_relationships, and sees
only the imports they requested. Connecting a Gmail or Outlook mailbox
from Settings starts its default import as the person who connected it;
a new LinkedIn account is offered in Actions for an owner's approval.
First fetch history_import_setup. Fetch history_import_preview with
contact_selection=recent (people who replied first, then the most recently
active, up to 1,000 identities; contacts_limited=true when more exist) or with selected person_ids
from history_import_people, plus source/date limits. Optional
discover_relationships=true permits empty person_ids. Explain bounded private
samples, model screening and quote verification, research-candidate
additions, evidence retention, and conditional undo. Model cost is internal
to Vruum: never state a model cost or budget, including
scope.discovery.max_model_micros.
- propose: no id. Payload {scope, scope_digest, client_request_id}; copy the
  preview's scope unchanged. Retain the UUID request ID on exact retries.
  This saves one review Action and reads no provider data.
- approve: id=run UUID. Show the saved scope and disclosures to the human
  before calling. Payload {scope_digest, expected_action_version} from a
  fresh fetch history_import. Approval authorizes metadata enumeration and
  matched bodies within saved limits. A discovery scope also authorizes its
  sampled model review and verified contact/account additions. Existing-only
  scopes run no models. Neither scope authorizes sending or qualification.
- pause/resume: id=run UUID, no payload. Preserve the exact approved scope.
  Reconnect the source in Integrations before retrying a disconnected run.
  Changed accounts/identities require a new preview and approval.
- stop: id=run UUID, no payload. End further work and retain captured history.
- remove: id=run UUID, no payload. Confirm removal with the human. Deletes
  this import's history and discovery evidence; untouched new memberships are
  archived. Changed records and memberships used elsewhere survive.

Poll fetch history_import; page history_import_batches for receipts.
Source completeness stays unverified, including after complete_with_gaps.
Read captured bodies through fetch relationship_history / relationship_history_detail,
subtype=people, id=person UUID. Never fabricate native message IDs.

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