Source: https://datafa.st/docs/api/account/funnels/create
Markdown source: https://datafa.st/docs/api/account/funnels/create.md
Description: Create a funnel with 2 to 8 steps.

# Create funnel

`POST https://datafa.st/api/v1/admin/websites/{websiteId}/funnels`

Create a conversion funnel with 2 to 8 ordered steps. Each step matches either a pageview (by URL) or a custom goal (by name).

Duplicate funnel names return **409**.

> **Related:** [Conversion funnels](/docs/conversion-funnels) · [Funnel analytics in the API](/docs/api/website/analytics/funnel-results)

## Request

#### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | — | Website ObjectId. From [List websites](/docs/api/account/websites/list) (`_id` field). Example: `665f0b3c4d2e1a0012345678`. |

#### Body parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Funnel display name. Example: `"Signup funnel"`. |
| `steps` | object[] | Yes | Ordered array of 2–8 steps. Each step needs `name`, `type`, and either `url` (pageview) or `goalName` (goal). |
| `steps[].name` | string | Yes | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `steps[].type` | `pageview` or `goal` | Yes | `"pageview"` — match a page URL. Requires `url`. `"goal"` — match a custom goal. Requires `goalName`. |
| `steps[].url` | string | If type is `pageview` | Page path or URL for a pageview step. Example: `"/pricing"` or `"/checkout"`. |
| `steps[].goalName` | string | If type is `goal` | Goal name for a goal step. Example: `"signup"`. Same naming rules as [Create goal](/docs/api/website/goals/create). Max 32 chars. |

#### Example request body

```json
{
  "name": "Signup funnel",
  "steps": [
    { "name": "Landing", "type": "pageview", "url": "/" },
    { "name": "Pricing", "type": "pageview", "url": "/pricing" },
    { "name": "Signup", "type": "goal", "goalName": "signup" }
  ]
}
```

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data`.

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[]._id` | string | Funnel ObjectId. |
| `data[].websiteId` | string | Website ObjectId used by account tokens to choose which website to query or manage. |
| `data[].name` | string | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data[].slug` | string | Generated slug. |
| `data[].steps` | object[] | Ordered funnel steps. |
| `data[].steps[].id` | string | Step ID. |
| `data[].steps[].name` | string | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data[].steps[].type` | string | `pageview` or `goal`. |
| `data[].steps[].url` | string | Page URL/path for pageview steps. |
| `data[].steps[].goalName` | string | Goal name for goal steps. |
| `data[].isActive` | boolean | Whether the funnel is active. |

### Authentication

Use a `dft_` account token with `funnels:write`.

A `df_` website API key for the same website can also call this route when the path `websiteId` matches the key's website. Write access with a `df_` key is capped at **member** level — owner-only actions such as [team management](/docs/api/account/team) require a `dft_` token and owner role.

### Errors

**400** — Invalid steps (wrong count, missing `url` or `goalName`, invalid goal name format).

**409** — Funnel with this name already exists.

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

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

### Success response

```json
{
  "status": "success",
  "data": [{
    "_id": "665f0b3c4d2e1a0012345678",
    "websiteId": "665f0b3c4d2e1a0012345678",
    "name": "Signup funnel",
    "slug": "signup-funnel",
    "steps": [
      { "id": "landing", "name": "Landing", "type": "pageview", "url": "/" },
      { "id": "signup", "name": "Signup", "type": "goal", "goalName": "signup" }
    ],
    "isActive": true,
    "createdAt": "2026-05-21T00:00:00.000Z"
  }]
}
```