---
title: "Manage Relationship Action"
method: POST
path: "/api/network/actions/manage"
tags: ["network"]
---

# Manage Relationship Action

`POST /api/network/actions/manage`

## Request

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

Draft, approve, and record the outcome of ONE warm-introduction attempt.

A "relationship action" is a single attempt to reach a target person
*through a mutual connection* rather than by contacting them directly:
asking a colleague for an intro, checking whether a connector actually
knows them, or requesting an entry into their company. `find_warm_path`
discovers those routes and never writes; this tool is the only way to act
on one.

**Use this instead of the direct-outreach tools when the path runs through
a person.** `manage_outreach` and `manage_messages` send to the target
themselves; `manage_engagements` handles reactions and comments on
content. This tool messages the *connector*.

**Nothing here auto-sends.** Every attempt walks a state machine you drive
one call at a time: `draft` creates it from a `result_ref` returned by
`find_warm_path`, then transitions approve the exact message text, confirm
that you sent it yourself outside Vruum, classify how the connector
replied, record the final outcome, or cancel. The response's
`approval_required` and `next_actions` fields tell you which transitions
are legal right now — read them rather than guessing.

Two consistency rules the server enforces:

- **`draft` is idempotent on `client_request_id`.** Reuse the same value
  when retrying a draft; a new value creates a second attempt.
- **Every transition needs `expected_version`.** A stale version means
  someone else moved the attempt and yours is rejected rather than
  silently overwriting — re-read the attempt and retry.

A `409 route_stale` on draft means the underlying relationship evidence
changed since it was reviewed; re-run `find_warm_path` and draft from a
fresh `result_ref`.

## Request body

- union
  - RelationshipDraftAction
    - `action` 'draft', required
    - `target` string, required
    - `result_ref` string, required
    - `client_request_id` string, required
    - `purpose` string, nullable
    - `message_text` string, nullable
    - `channel` 'email' | 'linkedin' | 'external'
  - RelationshipEditDraftAction
    - `attempt_ref` string, required
    - `expected_version` integer, required
    - `action` 'edit_draft', required
    - `message_text` string, required
  - RelationshipApproveAction
    - `attempt_ref` string, required
    - `expected_version` integer, required
    - `action` 'approve', required
  - RelationshipConfirmExternalAction
    - `attempt_ref` string, required
    - `expected_version` integer, required
    - `action` 'confirm_external', required
    - `sent` boolean, required
  - RelationshipClassifyResponseAction
    - `attempt_ref` string, required
    - `expected_version` integer, required
    - `action` 'classify_response', required
    - `response` 'can_intro' | 'knows_not_comfortable' | 'knows_not_well' | 'does_not_know' | 'needs_context' | 'no_response', required
  - RelationshipRecordOutcomeAction
    - `attempt_ref` string, required
    - `expected_version` integer, required
    - `action` 'record_outcome', required
    - `outcome` RelationshipOutcome, required
      - `status` 'conversation_booked' | 'routed_to_right_person' | 'introduction_made' | 'not_interested' | 'other', required
      - `note` string, nullable
  - RelationshipCancelAction
    - `attempt_ref` string, required
    - `expected_version` integer, required
    - `action` 'cancel', required

## Response `200`

Successful Response

- ManageRelationshipActionResponse
  - `status` string, required
  - `attempt` RelationshipAttempt, required
    - `ref` string, required
    - `relationship_owner_user_id` string, required
    - `action_type` 'connector_check' | 'reactivation' | 'introduction' | 'company_entry', required
    - `target_ref` string, required
    - `target_snapshot` object, required
    - `result_ref` string, required
    - `result_type` 'direct' | 'verified_intro' | 'intro_candidate' | 'company_entry', required
    - `connector_ref` string, nullable
    - `connector_snapshot` object, nullable
    - `purpose` string, nullable
    - `channel` 'email' | 'linkedin' | 'external', required
    - `sending_account_id` string, nullable
    - `client_request_id` string, required
    - `route_fingerprint` string, required
    - `message_text` string, required
    - `state` string, required
    - `version` integer, required
    - `provider_message_id` string, nullable
    - `provider_thread_id` string, nullable
    - `follow_up_at` string, nullable
    - `outcome` object, nullable
    - `sent_at` string, nullable
    - `responded_at` string, nullable
    - `closed_at` string, nullable
    - `created_at` string, required
    - `updated_at` string, required
    - `action_id` string, nullable
    - `action_state` string, nullable
  - `approval_required` boolean
  - `next_actions` string[]
  - `web_url` string, required

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `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)