Source: https://datafa.st/docs/api/account/funnels
Markdown source: https://datafa.st/docs/api/account/funnels.md
Description: List, create, update, and delete conversion funnels.

# Funnels

Use these endpoints to manage conversion funnel definitions. To query results for a funnel, use [funnel analytics](/docs/api/website/analytics/funnel-results).

Funnels are saved configurations: a name plus ordered steps. Each step can match a pageview or a goal. Once created, the same funnel can be viewed in the dashboard, through [funnel analytics](/docs/api/website/analytics/funnel-results), or from the CLI.

Base path: `https://datafa.st/api/v1/admin`

| Endpoint | Method | Path | Permission | Purpose |
|---|---|---|---|---|
| [List funnels](/docs/api/account/funnels/list) | GET | `/websites/{websiteId}/funnels` | `funnels:read` | List active funnels |
| [Create funnel](/docs/api/account/funnels/create) | POST | `/websites/{websiteId}/funnels` | `funnels:write` | Create a funnel |
| [Update funnel](/docs/api/account/funnels/update) | PUT | `/websites/{websiteId}/funnels/{funnelId}` | `funnels:write` | Update a funnel |
| [Delete funnel](/docs/api/account/funnels/delete) | DELETE | `/websites/{websiteId}/funnels/{funnelId}` | `funnels:write` | Soft-delete a funnel |

## Create a funnel

```sh
curl -X POST "https://datafa.st/api/v1/admin/websites/YOUR_WEBSITE_ID/funnels" \
  -H "Authorization: Bearer dft_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Signup funnel",
    "steps": [
      { "name": "Landing page", "type": "pageview", "url": "/" },
      { "name": "Signup page", "type": "pageview", "url": "/signup" },
      { "name": "Signed up", "type": "goal", "goalName": "signup" }
    ]
  }'
```

Funnels need 2 to 8 steps. A step can be a `pageview` with a `url`, or a `goal` with a `goalName`.

Related docs: [funnel analytics](/docs/api/website/analytics/funnel-results), [conversion funnels](/docs/conversion-funnels), [CLI funnels](/docs/cli-funnels).

## Code examples

### Create a funnel

```bash
curl -X POST "https://datafa.st/api/v1/admin/websites/YOUR_WEBSITE_ID/funnels" \
  -H "Authorization: Bearer dft_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Signup funnel",
    "steps": [
      { "name": "Landing page", "type": "pageview", "url": "/" },
      { "name": "Signup page", "type": "pageview", "url": "/signup" },
      { "name": "Signed up", "type": "goal", "goalName": "signup" }
    ]
  }'
```

### Success response

```json
{
  "status": "success",
  "data": [
    {
      "id": "665f0b3c4d2e1a0012345678",
      "name": "Signup funnel",
      "isActive": true,
      "steps": [
        { "name": "Landing page", "type": "pageview", "url": "/" },
        { "name": "Signed up", "type": "goal", "goalName": "signup" }
      ]
    }
  ]
}
```