Skip to content
Docs menu

Build on Venom Funnel and Outreach

Work with deals, pipelines, products, goals, reports and Outreach sequences from code or an agent, over REST or MCP, as the member whose People the deals link.

View .md

Venom Funnel is the deal pipeline built on Venom People: the people on a deal are People, and what you log on a deal lands on your own people as interactions. Outreach, the follow-up sequences, lives inside Funnel. Everything an agent needs from the board, the deal page, Settings and Reports is an MCP tool on /workspace/mcp/funnel and a REST route under /api/v1/funnel. Outreach also has its own REST API under /v1/outreach.

What you can build

  • Deals from your sign-up or billing system. Open a deal for a new account with POST /api/v1/funnel/deals (or funnel_deal_create), linking the people you already have in People, and move it with POST /api/v1/funnel/deals/{deal}/move when the account converts.
  • A call logger. After a call, log it on the deal and add a to-do with one PATCH /api/v1/funnel/deals/{deal} (log and todo). The to-do is a Venom Tasks issue linked to the deal.
  • Forecast and goal reports. Read the weighted forecast, win rate, velocity or lost reasons with GET /api/v1/funnel/reports and goal attainment with GET /api/v1/funnel/goals into your own dashboard.
  • Quotes from your catalogue. Keep products in sync with funnel_product_save and add product lines to a deal with POST /api/v1/funnel/deals/{deal}/items; the deal's value becomes their sum.
  • Event follow-ups. After a conference, list the people met there with funnel_outreach_event_preview and enroll them in a sequence with funnel_outreach_person_enroll (consent_basis: met_in_person, dry_run first).
  • A deal assistant. Connect venom-funnel and let an agent find stale deals with funnel_deal_list, read one with funnel_deal_get and prepare the next step for the member to review.

At a glance

Generated from the code on every docs build.

MCP endpoint https://cloud.usevenom.dev/workspace/mcp/funnel, server name venom-funnel
Connect claude mcp add --transport http venom-funnel https://cloud.usevenom.dev/workspace/mcp/funnel
MCP tools 38 (14 read, 24 write)
OAuth scopes funnel:read funnel:write; people:read and people:write also open these tools
REST twin 42 routes under https://cloud.usevenom.dev/api/v1
Outreach API 13 operations
Webhook events funnel.deal.created, funnel.deal.updated, funnel.deal.stage_changed, funnel.deal.archived

Authentication and scopes

A deal links the member's own People, so Funnel always acts as one member, the same caller as People:

  • A personal API key (vck_… with a member) acts as that member. Every org role can read and change deals today (Funnel's row in the role matrix is held at write for billing and viewer too). A key marked read-only reads only.
  • A team key has no member and is refused on every Funnel tool and /api/v1/funnel route, with a message that says so. The Outreach API under /v1/outreach is the exception: there a team key acts for the org (below).
  • An OAuth app needs funnel:read to use the tools and funnel:write to change anything. Grants made with people:read and people:write before Funnel had its own scopes still open Funnel's tools.
  • A service agent that an admin scoped to some apps reaches Funnel only when People is one of them, because Funnel runs as the People caller.

The caller sees what the member sees: deals with visibility: team only when they are in that team, and on each deal only the people they may see. A hidden contact shows as a count.

There is no Funnel add-on: every member of an organisation has it. A todo creates a Tasks issue, so it needs the Tasks add-on. A refused change answers 403 over REST, or a tool error that names funnel:write over MCP.

Outreach adds one rule: an API key or an agent counts as an agent for approval. funnel_outreach_run_approve and POST /v1/outreach/runs/{id}/approve are refused unless the sequence sends without approval; a person approves the draft in Funnel.

Worked example

Open a deal for a person you found with people_person_search, log the first call with a follow-up to-do, then move the deal on:

curl -X POST "$VENOM_CLOUD/api/v1/funnel/deals" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"title": "Example Co · GPU cluster", "value": 250000, "currency": "USD", "stage": "Qualified",
       "company": "Example Co", "expected_close": "2026-12-15",
       "people": [{"person": "0b7c6f0e-5a3e-4c0f-9a52-3a8f1d2c4b11", "role": "champion"}]}'

curl -X PATCH "$VENOM_CLOUD/api/v1/funnel/deals/<deal-id>" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"log": {"kind": "call", "summary": "Intro call. They want a quote for 8 nodes."},
       "todo": {"title": "Send the 8-node quote", "due": "2026-11-16"}}'

curl -X POST "$VENOM_CLOUD/api/v1/funnel/deals/<deal-id>/move" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"stage": "Proposal"}'

The same move over MCP, from any client connected to /workspace/mcp/funnel:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "funnel_deal_move",
              "arguments": { "deal": "<deal-id>", "stage": "Proposal", "format": "json" } } }

stage is a stage's name or id. Moving into a won or lost stage closes the deal; pass lost_reason for a lost one. Every move is kept in the deal's stage history.

Values, formats and behaviour

  • Money. Values in arguments are in major units (12500.50): value, a product's price, a line's price and a won_value goal's target. JSON answers carry valueMinor in minor units (cents).
  • Answers. Tools answer short markdown; pass format: "json" for structuredContent. The REST twin always answers JSON.
  • Deal ids. deal is the deal's id (a UUID). Pipelines, stages, products and fields also take a name (or a SKU for a product).
  • Deal value and product lines. While a deal has product lines, its value is their sum and a value you send is ignored.
  • Setup tools. Pipelines, stages, products, custom fields and goals change with the same checks as Settings: a new pipeline needs a won and a lost stage; a stage's kind changes only while it holds no deals; archiving a stage moves its deals to move_to; the default pipeline, or one with open deals, cannot be archived. A goal target of 0 or null removes the goal.
  • Reports. report is summary (default), conversion, win_rate, velocity, forecast, team or lost_reasons; range is 30d, 90d, 12m or ytd.
  • Retries. No Funnel tool takes an idempotency key, so a retried POST /api/v1/funnel/deals can open a second deal. Look the deal up with funnel_deal_list (query) before you retry a create.

Outreach

Outreach tools are part of Funnel (funnel_outreach_*, same endpoint and scopes). They list and read your sequences and those shared with your teams, save yours, enroll People with a consent basis, pause, resume or stop an enrollment, list a sequence's enrollments (funnel_outreach_enrollment_list), list the queue of drafts to approve or steps to send yourself, approve or skip a step, mark a tap-to-send step sent (funnel_outreach_run_mark_sent), and preview one step's draft for one person. funnel_outreach_person_enroll with dry_run enrolls nobody and lists who would be skipped and why (not_found, already_enrolled, opted_out, no_consent, no_address). Catch-ups use funnel_outreach_catchup_get and funnel_outreach_catchup_set (default, reminder or a catch-up sequence id).

Two arguments exist only on the MCP tools, not on their /api/v1 twins: team on funnel_outreach_sequence_save (share a sequence with a team) and sender on funnel_outreach_person_enroll (send your enrollments from your own Comms senders). Use MCP, or the Outreach API below, when you need them.

The Outreach API

/v1/outreach is Outreach's own REST API, with an org API key like the rest of /v1. A member's personal key acts as that member. A team key acts for the org: it lists every sequence, and a sequence it creates is owned by the key. The OpenAPI document is services/nodejs-cloud/contracts/outreach-openapi.yaml; the docs build lists its operations in the REST section of this page.

Route What
GET, POST /v1/outreach/sequences list sequences, create one (teamId shares it with a team)
GET, PUT, DELETE /v1/outreach/sequences/{id} read, replace or archive one (archiving stops every live enrollment)
GET /v1/outreach/enrollments?sequence_id=, POST /v1/outreach/enrollments list a sequence's enrollments; enroll people (sequenceId, personIds, dealId, consentBasis, sender)
POST /v1/outreach/enrollments/{id} pause, resume or stop one enrollment (action)
GET /v1/outreach/queue?kind=approval or kind=manual drafts to approve, or steps to send yourself
POST /v1/outreach/runs/{id}/approve, /skip, /tapped approve a draft (optionally with an edited subject or body), skip a step, mark a tap-to-send step sent

Its fields are camelCase, as in contracts/outreach-v1.schema.json (TypeScript types in contracts/outreach.ts, examples in contracts/fixtures/outreach). Every route is in the cloud API reference.

Rules for agents

  • Search People first (people_person_search), then link the person with funnel_deal_create or funnel_deal_update.
  • Move a deal when the situation changes and log what happened with log: the forecast and the people's context cards depend on both.
  • A hidden contact shows as a count. Do not try to find out who it is.
  • Never contact anyone on the user's behalf. Draft, and let the user approve or send.

Events

4 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).

Event When
funnel.deal.created A deal visible to the whole org was created in Venom Funnel: id, title, value, currency, pipeline, stage, status, owner and company. Never its notes or the people on it; a team-only deal is never sent.
funnel.deal.updated An org-wide deal's own fields changed (title, value, owner, company, expected close), or a team deal was opened to the org: the deal as it is now. A deal moved from the org to a team sends its id and visibility only.
funnel.deal.stage_changed An org-wide deal moved to another stage: the stage before and after, its status (open, won or lost) as it is now, and who moved it.
funnel.deal.archived An org-wide deal was archived: its id and title.

Funnel and Outreach send no org webhook events. To follow changes, read deals with funnel_deal_list (sort and filter by stage, status or owner) or a deal's history with funnel_deal_get.

REST routes

The REST twin: 42 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).

/funnel/pipelines

Method Path Summary MCP tool
GET /api/v1/funnel/pipelines List pipelines with their stages funnel_pipeline_list
POST /api/v1/funnel/pipelines Make a pipeline with its stages funnel_pipeline_create
GET /api/v1/funnel/pipelines/{pipeline} Read a pipeline with the count and value of its deals per stage funnel_pipeline_get
PATCH /api/v1/funnel/pipelines/{pipeline} Rename a pipeline or make it the default funnel_pipeline_update
DELETE /api/v1/funnel/pipelines/{pipeline} Archive a pipeline (no open deals, not the default) funnel_pipeline_archive
POST /api/v1/funnel/pipelines/{pipeline}/stages Add a stage to a pipeline funnel_stage_create
PUT /api/v1/funnel/pipelines/{pipeline}/stages Put a pipeline's stages in this order funnel_stage_update

/funnel/reports

Method Path Summary MCP tool
GET /api/v1/funnel/reports Conversion, win rate, velocity, the weighted forecast and the team funnel_report_get

/funnel/goals

Method Path Summary MCP tool
GET /api/v1/funnel/goals Sales goals with attainment and pace funnel_goal_list
PUT /api/v1/funnel/goals Set a sales goal (target 0 or null removes it), or change one by its goal id funnel_goal_set

/funnel/deals

Method Path Summary MCP tool
GET /api/v1/funnel/deals List deals you may see funnel_deal_list
POST /api/v1/funnel/deals Open a deal funnel_deal_create
GET /api/v1/funnel/deals/{deal} Read a deal with its people, lines, history, activity and to-dos funnel_deal_get
PATCH /api/v1/funnel/deals/{deal} Change a deal, log an activity, add a to-do funnel_deal_update
POST /api/v1/funnel/deals/{deal}/move Move a deal to a stage funnel_deal_move
POST /api/v1/funnel/deals/{deal}/items Add a product line to a deal funnel_item_create
PATCH /api/v1/funnel/deals/{deal}/items/{item} Change a line of a deal funnel_item_update
DELETE /api/v1/funnel/deals/{deal}/items/{item} Remove a line from a deal funnel_item_delete

/funnel/stages

Method Path Summary MCP tool
PATCH /api/v1/funnel/stages/{stage} Rename a stage or change its probability, type or stale-after days funnel_stage_update
DELETE /api/v1/funnel/stages/{stage} Archive a stage, moving its deals to move_to funnel_stage_archive

/funnel/products

Method Path Summary MCP tool
GET /api/v1/funnel/products The product catalogue funnel_product_list
POST /api/v1/funnel/products Add a product funnel_product_save
PATCH /api/v1/funnel/products/{product} Change, archive or restore a product funnel_product_save

/funnel/outreach

Method Path Summary MCP tool
GET /api/v1/funnel/outreach/sequences Your outreach sequences with their steps and counts funnel_outreach_sequence_list
POST /api/v1/funnel/outreach/sequences Create an outreach sequence funnel_outreach_sequence_save
GET /api/v1/funnel/outreach/sequences/{sequence} Read an outreach sequence funnel_outreach_sequence_get
PUT /api/v1/funnel/outreach/sequences/{sequence} Replace one of your outreach sequences funnel_outreach_sequence_save
POST /api/v1/funnel/outreach/enrollments Enroll People in an outreach sequence funnel_outreach_person_enroll
POST /api/v1/funnel/outreach/enrollments/{enrollment} Pause, resume or stop an enrollment funnel_outreach_enrollment_set
GET /api/v1/funnel/outreach/queue Drafts to approve or steps to send by hand funnel_outreach_queue_list
POST /api/v1/funnel/outreach/runs/{run}/approve Approve an outreach draft funnel_outreach_run_approve
GET /api/v1/funnel/outreach/sequences/{sequence}/enrollments A sequence's enrollments: who is in it, at which step, and why one stopped funnel_outreach_enrollment_list
POST /api/v1/funnel/outreach/runs/{run}/mark-sent Record that you sent a tap-to-send step yourself (Venom sends nothing); the enrollment moves on funnel_outreach_run_mark_sent
POST /api/v1/funnel/outreach/runs/{run}/skip Skip an outreach step funnel_outreach_run_skip
POST /api/v1/funnel/outreach/runs/{run}/hold Hold a timed draft so it never sends by itself funnel_outreach_run_hold
POST /api/v1/funnel/outreach/sequences/{sequence}/preview Preview a step's draft for one person funnel_outreach_draft_preview
GET /api/v1/funnel/outreach/catchups/{person} What a person's keep-warm cadence runs when it comes due funnel_outreach_catchup_get
PUT /api/v1/funnel/outreach/catchups/{person} Set a person's catch-up: default, reminder or a catch-up sequence funnel_outreach_catchup_set
GET /api/v1/funnel/outreach/events/{event} The people met at an event, ready to enroll funnel_outreach_event_preview

/funnel/fields

Method Path Summary MCP tool
GET /api/v1/funnel/fields The org's custom deal fields funnel_field_list
POST /api/v1/funnel/fields Add a custom deal field funnel_field_save
PATCH /api/v1/funnel/fields/{field} Change, archive or restore a custom field funnel_field_save

Also the Outreach API: 13 operations, generated from services/nodejs-cloud/contracts/outreach-openapi.yaml. "Key or token" is a Venom API key or an OAuth access token; SDK keys and client ids belong to an environment and are for your app's runtime.

Method Path Summary Auth
GET /v1/outreach/sequences List sequences (yours and those shared with your teams; a team key sees every one) key or token
POST /v1/outreach/sequences Create a sequence (status draft unless given; approval every unless given) key or token
GET /v1/outreach/sequences/{id} Read a sequence key or token
PUT /v1/outreach/sequences/{id} Replace one of your sequences (steps replace its steps in order) key or token
DELETE /v1/outreach/sequences/{id} Archive one of your sequences; everyone still in it stops key or token
GET /v1/outreach/enrollments A sequence's enrollments, newest first (in a sequence shared with your team, only your own) key or token
POST /v1/outreach/enrollments Enroll People in a sequence, with the consent basis for contacting them key or token
POST /v1/outreach/enrollments/{id} Pause, resume or stop one of your enrollments key or token
GET /v1/outreach/queue What waits on you, oldest first (drafts to approve, or steps to send yourself) key or token
POST /v1/outreach/runs/{id}/approve Approve a draft, optionally edited; it goes out inside the send window key or token
POST /v1/outreach/runs/{id}/skip Skip a step; the enrollment moves on to the next key or token
POST /v1/outreach/runs/{id}/hold Hold a draft so it never sends by itself (a timed sequence's timer is removed); it waits for a person key or token
POST /v1/outreach/runs/{id}/tapped Record that you sent a tap-to-send step (or did a task) yourself key or token

MCP tools

38 tools: 14 read, 24 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.

Tool Title Access Scope REST route
funnel_deal_create Create a deal write funnel:write POST /api/v1/funnel/deals
funnel_deal_get Read a deal read funnel:read GET /api/v1/funnel/deals/{deal}
funnel_deal_list List deals read funnel:read GET /api/v1/funnel/deals
funnel_deal_move Move a deal to a stage write funnel:write POST /api/v1/funnel/deals/{deal}/move
funnel_deal_update Change a deal write funnel:write PATCH /api/v1/funnel/deals/{deal}
funnel_field_list List custom fields read funnel:read GET /api/v1/funnel/fields
funnel_field_save Add or change a custom field write funnel:write POST /api/v1/funnel/fields (+1)
funnel_goal_list List sales goals read funnel:read GET /api/v1/funnel/goals
funnel_goal_set Set or remove a sales goal write funnel:write PUT /api/v1/funnel/goals
funnel_item_create Add a line to a deal write funnel:write POST /api/v1/funnel/deals/{deal}/items
funnel_item_delete Remove a line from a deal write (destructive) funnel:write DELETE /api/v1/funnel/deals/{deal}/items/{item}
funnel_item_update Change a line of a deal write funnel:write PATCH /api/v1/funnel/deals/{deal}/items/{item}
funnel_outreach_catchup_get Read a person's catch-up setting read funnel:read GET /api/v1/funnel/outreach/catchups/{person}
funnel_outreach_catchup_set Set a person's catch-up sequence write funnel:write PUT /api/v1/funnel/outreach/catchups/{person}
funnel_outreach_draft_preview Preview an outreach draft write funnel:write POST /api/v1/funnel/outreach/sequences/{sequence}/preview
funnel_outreach_enrollment_list List a sequence's enrollments read funnel:read GET /api/v1/funnel/outreach/sequences/{sequence}/enrollments
funnel_outreach_enrollment_set Pause, resume or stop an enrollment write funnel:write POST /api/v1/funnel/outreach/enrollments/{enrollment}
funnel_outreach_event_preview Preview an event follow-up read funnel:read GET /api/v1/funnel/outreach/events/{event}
funnel_outreach_person_enroll Enroll people in a sequence write funnel:write POST /api/v1/funnel/outreach/enrollments
funnel_outreach_queue_list List the outreach queue read funnel:read GET /api/v1/funnel/outreach/queue
funnel_outreach_run_approve Approve an outreach draft write funnel:write POST /api/v1/funnel/outreach/runs/{run}/approve
funnel_outreach_run_hold Hold an outreach draft write funnel:write POST /api/v1/funnel/outreach/runs/{run}/hold
funnel_outreach_run_mark_sent Mark a tap-to-send step sent write funnel:write POST /api/v1/funnel/outreach/runs/{run}/mark-sent
funnel_outreach_run_skip Skip an outreach step write funnel:write POST /api/v1/funnel/outreach/runs/{run}/skip
funnel_outreach_sequence_get Read an outreach sequence read funnel:read GET /api/v1/funnel/outreach/sequences/{sequence}
funnel_outreach_sequence_list List outreach sequences read funnel:read GET /api/v1/funnel/outreach/sequences
funnel_outreach_sequence_save Create or change an outreach sequence write funnel:write POST /api/v1/funnel/outreach/sequences (+1)
funnel_pipeline_archive Archive a pipeline write (destructive) funnel:write DELETE /api/v1/funnel/pipelines/{pipeline}
funnel_pipeline_create Create a pipeline write funnel:write POST /api/v1/funnel/pipelines
funnel_pipeline_get Read a pipeline read funnel:read GET /api/v1/funnel/pipelines/{pipeline}
funnel_pipeline_list List pipelines read funnel:read GET /api/v1/funnel/pipelines
funnel_pipeline_update Rename a pipeline write funnel:write PATCH /api/v1/funnel/pipelines/{pipeline}
funnel_product_list List products read funnel:read GET /api/v1/funnel/products
funnel_product_save Add or change a product write funnel:write POST /api/v1/funnel/products (+1)
funnel_report_get Read a funnel report read funnel:read GET /api/v1/funnel/reports
funnel_stage_archive Archive a stage write (destructive) funnel:write DELETE /api/v1/funnel/stages/{stage}
funnel_stage_create Add a stage write funnel:write POST /api/v1/funnel/pipelines/{pipeline}/stages
funnel_stage_update Change or reorder stages write funnel:write PUT /api/v1/funnel/pipelines/{pipeline}/stages (+1)