FunnelFox API reference

The FunnelFox API provides read access to your funnel data, enabling you to retrieve information about funnels, user profiles, sessions, subscriptions, and products. Use it to build custom dashboards, sync data with external systems, or create detailed reports.

This doc covers the FunnelFox API only. If you’re using the FunnelFox Billing API, go to the Billing API section.

Base URL

All API requests should be made to:

https://api.funnelfox.io/public/v1

Authentication

Every API request requires authentication using your project’s secret key via the Fox-Secret header.

curl https://api.funnelfox.io/public/v1/funnels \
  -H "Fox-Secret: secret_your_key_here"

This is the same secret key used for webhooks. Never expose it in client-side code or public repositories. Keep it secure on your server.

Quick Start

Get Your Secret Key

Find your Fox-Secret in Project Settings

Make Your First Request

Test the API with a simple funnels list request:

curl https://api.funnelfox.io/public/v1/funnels \
  -H "Fox-Secret: secret_your_key"

Parse the Response

Handle the JSON response with pagination metadata

Build Your Integration

Use the data to power your analytics, reporting, or automation

Available Endpoints

The API provides read access to core FunnelFox data, plus an endpoint to anonymize profiles:

Funnels

GET /funnels - List all funnels
GET /funnels/{id} - Get funnel details

Monitor funnel performance and configuration

Profiles & Sessions

GET /profiles/{id} - Get user profile
POST /profiles/anonymize - Anonymize profiles (GDPR erasure)
GET /sessions/{id} - Get session data
GET /sessions/{id}/replies - Get form responses

Track user journeys and collected data

Subscriptions

GET /subscriptions - List subscriptions
GET /subscriptions/{id} - Get subscription details

Monitor recurring revenue and subscription states

Products

GET /products - List all products
GET /products/{id} - Get product details

Access your product catalog data

Making Requests

Request Headers

All requests must include:

Header	Required	Description
`Fox-Secret`	Yes	Your project’s secret key
`Content-Type`	No	Set to `application/json` for POST requests

Example Request

// Node.js with fetch
const response = await fetch('https://api.funnelfox.io/public/v1/funnels', {
  headers: {
    'Fox-Secret': process.env.FUNNELFOX_SECRET
  }
});

const data = await response.json();
console.log(`Found ${data.data.length} funnels`);

Response Format

All successful responses follow this structure:

{
  "data": [...],  // Array of requested resources
  "pagination": {
    "cursor": "abc123",  // Use for next page
    "has_more": true     // More results available
  }
}

Pagination

The API uses cursor-based pagination for list endpoints. The cursor represents the ID of the last item in the current page.

# First page
GET /funnels?limit=20

# Next page using cursor from previous response
GET /funnels?limit=20&cursor=abc123

Pagination parameters:

limit - Number of items per page (1-100, default: 20)
cursor - ID of the last item from previous page

// Paginating through all funnels
async function getAllFunnels() {
  const funnels = [];
  let cursor = null;
  
  do {
    const url = new URL('https://api.funnelfox.io/public/v1/funnels');
    url.searchParams.set('limit', '50');
    if (cursor) url.searchParams.set('cursor', cursor);
    
    const response = await fetch(url, {
      headers: { 'Fox-Secret': SECRET }
    });
    
    const data = await response.json();
    funnels.push(...data.data);
    
    cursor = data.pagination.has_more ? data.pagination.cursor : null;
  } while (cursor);
  
  return funnels;
}

Error Handling

The API returns standard HTTP status codes and JSON error messages:

Error Response Format

{
  "message": "Description of the error"
}

Filtering & Querying

Many endpoints support filtering to narrow down results:

Funnel Filters

# Filter by title
GET /funnels?filter[title]=welcome

# Filter by alias
GET /funnels?filter[alias]=onboarding

# Filter by type
GET /funnels?filter[type]=cancellation

# Include deleted funnels
GET /funnels?filter[deleted]=true

# Combine filters
GET /funnels?filter[type]=default&filter[title]=pricing&limit=10

Subscription Filters

# Filter by status
GET /subscriptions?filter[status]=active

# Filter by product
GET /subscriptions?filter[product_id]=prod_123

# Filter by date range (if supported)
GET /subscriptions?filter[created_after]=2024-01-01

Troubleshooting

401 Unauthorized errors

Verify your Fox-Secret is correct
Check you’re using the header name Fox-Secret (case-sensitive)
Ensure the secret hasn’t been regenerated in Project Settings

Empty data arrays

Check your filters aren’t too restrictive
Verify the resources exist in your project
Ensure you’re using the correct IDs

Pagination not working

Use the exact cursor value from the previous response
Don’t modify or decode the cursor
Check has_more before requesting next page

404 Not Found

Verify the endpoint URL is correct
Check the resource ID exists
Ensure you’re using the v1 API path

What’s Next

[API Reference](/api-reference/list-funnels - Detailed endpoint documentation
Webhooks - Real-time event notifications
Project Settings - Manage your API credentials

​Base URL

​Authentication

​Quick Start

​Available Endpoints

Funnels

Profiles & Sessions

Subscriptions

Products

​Making Requests

​Request Headers

​Example Request

​Response Format

​Pagination

​Error Handling

​Error Response Format

​Filtering & Querying

​Funnel Filters

​Subscription Filters

​Troubleshooting

​What’s Next

Base URL

Authentication

Quick Start

Available Endpoints

Making Requests

Request Headers

Example Request

Response Format

Pagination

Error Handling

Error Response Format

Filtering & Querying

Funnel Filters

Subscription Filters

Troubleshooting

What’s Next