Funnels

A funnel is Perspective's core building block for converting visitors into contacts. It is a multi-page, interactive web experience — think quiz, lead-gen flow, booking form, or survey — that guides a visitor through a sequence of pages and captures their information when they convert. Each funnel lives at a URL (the liveUrl once published to a custom domain, or the previewUrl for sharing before publishing) and collects the data that populates your CRM contacts.

Why funnels are the center of gravity

Almost every other resource in the Perspective API is scoped to a funnel. Contacts belong to a funnel, metrics are measured per funnel, and CRM properties are defined at the funnel level. The funnelId (also called a campaignId in the workspaces endpoint) is therefore the primary identifier you will use across the whole API.

A funnel ID looks like fnl_abc123. Once you have one, you can:

• Retrieve the contacts who converted through it (GET /v1/funnels/{funnelId}/contacts)
• Pull KPIs and chart data for it (GET /v1/funnels/{funnelId}/metrics/...)
• Create contacts in it programmatically (POST /v1/funnels/{funnelId}/contacts)

Discovering your funnel IDs

The starting point for discovering funnel IDs is GET /v1/workspaces. This single call returns all workspaces and, nested inside each, all campaigns (funnels) with their IDs, names, and publication status. Each funnel entry includes its id, name, previewUrl, and (when published) liveUrl. Copy the id from a campaigns entry — that is the funnelId you pass everywhere else. See the Quickstart for a step-by-step walkthrough.

Building and editing funnels via MCP

The MCP server exposes a richer funnel-builder capability aimed at AI assistants. Through the MCP tools for funnels, an AI agent can:

• List existing funnels and retrieve their current HTML
• Create a new funnel from scratch, guided by brand identity and conversion strategy
• Update an existing funnel's HTML — either targeted find/replace patches or a full HTML replacement
• Rename, set slugs, and manage publication status

The funnel-builder skill used by the MCP server follows a structured flow: it picks a brand, classifies the funnel into a category (lead-gen quiz, appointment, VSL, etc.), loads the corresponding formula scaffold, and generates a fully tracked single-file HTML funnel.

See the MCP Funnels tools reference for the full list of available tools and their parameters.

Funnel objects at a glance

Every funnel response includes these core fields:

Field	What it is
id	Unique identifier (fnl_…). The funnelId you pass to all other endpoints.
name	Human-readable display name as set in the Perspective dashboard or via the API.
previewUrl	Always present. Use this to preview the funnel without a custom domain.
liveUrl	Present only when the funnel is published to a custom domain.
coverImage	Present only when a cover image has been generated for the funnel.

Next steps

• Workspaces and Campaigns — how workspaces group funnels and how IDs flow
• Contacts and CRM — the contacts a funnel collects
• MCP Funnels tools — build and edit funnels through an AI assistant