# Creating Funnels

Creating funnels through the API is complex. We recommend doing this only if you have developer support and a strong understanding of FunnelFlux funnel logic.

If you do wish to create funnels via API, please see the following important notes and best practices.

## Use the UI to first understand funnel data

Before creating via API you should create simple funnels in our user interface and inspect the network requests.

You will see how our UI creates certain assets first (like page groups and conditions), successfully saves these, and then saves the funnel once the underlying nodes that are referred to have been created.

You will also be able to see the full payloads of data going to the backend.

## Always use ID generation

Refer to [Generating Asset IDs](/id-generation) alongside this page. You must generate appropriate IDs for all assets created in FunnelFlux Pro, including nodes, pages, funnels, page groups, and conditions.

If you fail to do this correctly, the assets may still save because the asset database does not strictly enforce ID length. The data may then be truncated in the analytics database, which does have stricter data types.

In that event, your reporting for that funnel will be broken and unrecoverable.

You should generate these IDs on your side with code and ensure you reference correctly. For example if you make a new page group, you should create it first via API, then reference that underlying page group in the funnel, with the page group node having its own separate unique ID (a node ID and the underlying page group asset it references are different).

## Ensure nodes have valid config

Our frontend UI does a lot of validation, such as checking that conditions have a connection for each route and page groups have at least one page in them.

Ensure you also do sensible validation in your funnels to prevent nodes with invalid config, which could lead to a click going nowhere and causing an error (and loss on your side).

You should always test your own funnels and tracking.

## Assets referenced in funnel data

The following node types have an underlying asset stored outside of the funnel data:

- Page groups
  - Lander groups
  - Offer groups
- Conditions

When you create a page group node (whether it be an offer or a lander group), it creates a local node in the funnel that references an underlying page group ID.

That page group asset then references other specific page IDs.

Since these references occur, you need to create the underlying assets *before* saving the funnel, to ensure referencing is complete.

## Restricting assets to a funnel ID (default approach)

When creating page groups or conditions, there is a property `restrictToFunnelId`.

This property should be filled with the funnel ID you are using the node in, which will make it a local group only available in this funnel.

If this property is absent, the page group/condition will be considered "global" and can be used in multiple funnels.

It will then appear on the page group/conditions pages and in your global assets list in the node palette.

This is generally not desired unless you specifically want to reuse the asset across multiple funnels, so ensure `restrictToFunnelId` is used by default.

## Global page group categories

Only global page groups are category-managed. Local funnel-scoped page groups are not moved through the page group category endpoints.

Use `categoryType=landerGroup` for global lander groups and `categoryType=offerGroup` for global offer groups.

The Assets API supports both legacy and clean page group category paths:

```text
GET /page/group/find/byCategory/
PUT /page/group/move-category/
GET /pagegroup/find/byCategory/
PUT /pagegroup/move-category/
```

Use `idCategory: ""` when moving a global page group back to Uncategorized.