> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pocketsflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sales funnels

> Create, activate and measure sales funnels with your API key or from an AI agent over MCP.

A funnel ties a free **lead magnet** product to an email **sequence** (a real
automation with real email posts) and a paid **offer**. The API creates it
from a template, turns it on and reports its numbers. Product guide:
[Sales funnels](/selling/sales-funnels).

<Note>
  Growth plan and above. `POST /funnels` and `POST /funnels/{id}/activate`
  answer `403` with `code: FEATURE_LOCKED` (and `details.requiredPlan`) on a
  plan without funnels. Listing, reading, pausing and deleting stay open.
</Note>

## Endpoints

| Method | Endpoint | Operation ID | MCP tool |
| - | - | - | - |
| `GET` | `/funnels/templates` | `listFunnelTemplates` | `list_funnel_templates` |
| `GET` | `/funnels` | `listFunnels` | `list_funnels` |
| `POST` | `/funnels` | `createFunnel` | `create_funnel` |
| `GET` | `/funnels/{id}` | `getFunnel` | `get_funnel` |
| `PUT` | `/funnels/{id}` | `renameFunnel` | — |
| `DELETE` | `/funnels/{id}` | `deleteFunnel` | — |
| `POST` | `/funnels/{id}/activate` | `activateFunnel` | `activate_funnel` |
| `POST` | `/funnels/{id}/pause` | `pauseFunnel` | `pause_funnel` |
| `GET` | `/funnels/{id}/stats` | `getFunnelStats` | `get_funnel_stats` |

Funnels live in the key's mode: a `pk_test_` key sees test-mode funnels and
products only.

## Create a funnel

```bash theme={"system"}
curl https://api.pocketsflow.com/funnels \
  -H "Authorization: Bearer $POCKETSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "welcome",
    "leadMagnetProductId": "665f1c2a9b3e4a0012ab34cd",
    "offerProductId": "665f1c2a9b3e4a0012ab34ce",
    "offerUrl": "https://acme.pocketsflow.com/notion-os",
    "discount": { "code": "FUNNEL20", "valueType": "percentage", "value": 20 }
  }'
```

| Field | Required | Notes |
| - | - | - |
| `templateId` | yes | `welcome` (5 emails over 7 days), `minicourse` (4 lessons, one a day) or `launch` (3 emails over 72 hours). |
| `leadMagnetProductId` | yes | One of your free products ($0, or pay what you want from $0). |
| `offerProductId` | yes | One of your paid products. |
| `offerUrl` | yes | The http(s) link the offer emails use. The discount code is appended as `?discount=`. |
| `discount` | no | `{ code, valueType, value, expiresAt }`. Creates a new code for the offer product (3–32 letters, numbers, `-`, `_`). |
| `name` | no | Defaults to `<lead magnet> → <offer>`. |

The answer is the funnel with `status: "draft"`, its `automationId` and its
`emailPostIds`. Edit the emails with the [posts endpoints](/api-reference/endpoints#posts)
before you activate it if you like.

Errors: `400` with `code` `LEAD_MAGNET_NOT_FREE`, `OFFER_NOT_PAID` or
`DISCOUNT_CODE_TAKEN`; `403` `FEATURE_LOCKED`.

## Activate

```bash theme={"system"}
curl -X POST https://api.pocketsflow.com/funnels/6710c3d59e3f1a0012cd7a01/activate \
  -H "Authorization: Bearer $POCKETSFLOW_API_KEY"
```

Activation turns the funnel's automation on under the same rules as any
automation, plus two funnel checks:

| Status | `code` / `error` | Meaning |
| - | - | - |
| `403` | `PAID_PLAN_REQUIRED` | Automations need a paid plan. |
| `403` | `FEATURE_LOCKED` | Your plan does not include funnels. |
| `400` | `SENDER_NOT_VERIFIED` | Verify your sender email in Email settings first. |
| `400` | `EMAILS_MISSING` | An email node points at no email post. |
| `409` | `SEQUENCE_MISSING` | The funnel's automation was deleted. |

## Stats

`GET /funnels/{id}/stats` returns:

* `totals`: `leads`, `emailsSent`, `opens`, `clicks`, `purchases`, `buyers`,
  `revenue`, `conversionRate` (percent), `currency` (your account currency).
* `stages`: unique people who got the lead magnet, opened, clicked and
  bought.
* `emails`: per email, in send order, `sent`, `opened` and `clicked`.

A purchase counts for the funnel when the buyer's email got the lead magnet
first and bought the offer within **30 days** (`attributionWindowDays`).
Refunded sales never count.

## Webhook: `funnel.lead`

Fired once per new lead (a repeat claim never fires it again). Subscribe to
it with `POST /webhooks`.

```json theme={"system"}
{
  "id": "evt_6a43ce05fae6c4f0cb5a2193",
  "type": "funnel.lead",
  "created": 1767225600,
  "webhookId": "6710c3d59e3f1a0012cd7c01",
  "funnel": {
    "id": "6710c3d59e3f1a0012cd7a01",
    "name": "Free Notion Starter → Notion Business OS",
    "leadMagnetProductId": "665f1c2a9b3e4a0012ab34cd",
    "offerProductId": "665f1c2a9b3e4a0012ab34ce"
  },
  "lead": {
    "email": "ana@example.com",
    "firstName": "Ana",
    "lastName": "Reader",
    "subscriberId": "6710c3d59e3f1a0012cd7b11",
    "subscribed": true,
    "tag": "lead-free-notion-starter"
  },
  "order": { "id": "6710c3d59e3f1a0012cd7b12" },
  "capturedAt": "2026-10-16T09:41:07.000Z"
}
```

`subscribed: false` means the person had unsubscribed before: they count as
a lead but get no emails.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.