Multi-step lead-gen funnels - screens, blocks, scoring, A/B variants, server-side pixel + CAPI dispatch. Same token model as the rest of the API.
Base URL: https://formspring.io/api/v1
| Method | Path | Ability |
|---|---|---|
| GET | /funnels |
funnels:read |
| POST | /funnels |
funnels:write |
| GET | /funnels/{funnel} |
funnels:read |
| PUT | /funnels/{funnel} |
funnels:write |
| DELETE | /funnels/{funnel} |
funnels:write |
| POST | /funnels/{funnel}/publish |
funnels:publish |
| POST | /funnels/{funnel}/unpublish |
funnels:publish |
| GET | /funnels/{funnel}/analytics |
funnels:analytics |
| GET | /funnels/{funnel}/sessions |
funnels:analytics |
Funnels require a paid plan - 402 on Free.
The {funnel} path parameter accepts the funnel's slug.
List funnels
GET /funnels
GET /funnels?project_id={project_public_id}
Returns all active funnels for the current team. Optional project_id query scopes to a single project.
Each row carries screens_count, sessions_count, and submissions_count so the UI can render a triage table without a second round-trip.
Create a funnel
POST /funnels
Content-Type: application/json
{
"name": "Spring 2026 - homebuyer guide",
"slug": "homebuyer-guide"
}
namerequired (max 120 chars)slug- URL slug under/u/{slug}. Auto-generated when omitted.
Created funnels start unpublished with an empty screens array. Add screens + blocks via PUT /funnels/{funnel} or through the dashboard builder.
Response 201: FunnelResource.
Show a funnel
GET /funnels/{funnel}
The show response eager-loads screens and each screen's blocks array (with each block's score map) so a single call hydrates the whole builder document. It also carries outcomes: the funnel's score bands (key, score_min, score_max, score_bucket, and screen_id, the id of the ending screen in screens). Scores are computed by Formspring on submit and cannot be set through this API.
Update a funnel
PUT /funnels/{funnel}
Content-Type: application/json
{
"name": "Homebuyer Guide - A/B variant B",
"tracking": {
"ga4_id": "G-XXXXXXX",
"meta_pixel_id": "1234567890"
},
"ab_test_config": {
"enabled": true,
"variants": [{ "key": "a", "weight": 50 }, { "key": "b", "weight": 50 }]
},
"screens": [
{ "position": 0, "kind": "welcome", "config": { "heading": "Find your home" } },
{ "position": 1, "kind": "question", "config": { "prompt": "Bedrooms?" } },
{ "position": 2, "kind": "form-collect", "config": { "fields": ["email"] } },
{ "position": 3, "kind": "thank-you", "config": { "heading": "Thanks!" } }
]
}
ab_test_config also takes the predeclared plan the test is judged by: primary_metric (completion, lead, qualified, booking or order), min_sample_per_variant, horizon_sample_per_variant and horizon_end_at. A running test needs two distinct variants with a share of the visitors; stopping it (enabled: false) keeps every assignment and result.
settings accepts qualification (enabled, version, match of all or any, and rules, each either { "type": "min_score", "bucket"?, "min" } or { "type": "outcome", "keys": [] }) and crm_stage_map (a map of CRM stage name to won or lost). Each replaces the stored value. An enabled qualification needs at least one usable rule. Both are returned under settings on the funnel.
Sending screens replaces the whole screen array in a single transaction. Blocks within each screen are managed through screen config or the MCP add_block / set_logic tools.
Allowed screen kinds are listed in Funnel::SCREEN_KINDS (welcome, question, form-collect, thank-you, redirect, ...).
Publish / unpublish
POST /funnels/{funnel}/publish
POST /funnels/{funnel}/unpublish
Publishing flips is_published = true + stamps published_at. Unpublishing flips is_published = false; the public /u/{slug} URL stops serving the funnel.
These two endpoints require the dedicated funnels:publish ability (separate from funnels:write so admins can issue tokens that edit funnel content without going-live capability).
Delete a funnel
DELETE /funnels/{funnel}
Soft-deletes the funnel and flips is_published off. Sessions are preserved for audit history; screens/blocks/scoring rules cascade away on permanent purge from the admin panel.
Analytics
GET /funnels/{funnel}/analytics
Returns the aggregated funnel summary - total sessions, completion rate, step-by-step drop-off, A/B-variant attribution. Requires funnels:analytics.
A funnel with score bands also returns outcomes and scored_total: for each band, its key, label (the ending's headline, else the key), screen_id, count and share of the scored, non-spam submissions (scored_total). Both are empty ([] and 0) for a funnel without bands, and the from / to filters apply.
GET /funnels/{funnel}/sessions
Returns the 100 most-recent funnel sessions (started, completed, current screen, A/B variant, UTM context). Capped server-side; for full export use the dashboard CSV stream.
Attribution report
GET /funnels/{funnel}/attribution?model=first_touch&lookback_days=30&from=2026-10-01&to=2026-10-31
Leads, qualified leads, bookings and orders by source, CRM won and lost, attributed and unattributed lead counts, and gross, adjusted and net revenue per currency. Requires funnels:analytics.
| Parameter | Meaning |
|---|---|
model |
journey_source (default: the source stored on the journey), first_touch, last_touch or linear (an outcome shared equally across the visits that led to it, so counts can be fractions). |
lookback_days |
1-90. Touch models only: leave out visits more than this many days before the visit that converted. |
from, to |
Date window on when the outcome happened. |
A direct visit never takes credit from a campaign or referrer visit. Visitors who did not allow analytics are reported as (unattributed) under every model. The response echoes the model, the lookback_days it applied and the list of models. Without a model, the report uses the funnel's saved default (settings.attribution: { "model": "first_touch", "lookback_days": 30 }, written through PUT /funnels/{funnel}); naming a model overrides the saved window as well.
Errors
| Status | When |
|---|---|
| 402 | Plan doesn't include funnels |
| 403 | Token missing required ability |
| 404 | Funnel doesn't belong to the current team |
See also
- Tokens & abilities →
- MCP server → - funnel screen authoring (
add_screen,add_block,set_logic,set_score,set_pixel,set_capi_token)
