Skip to main content
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

1

Get Your Secret Key

Find your Fox-Secret in Project Settings
2

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"
3

Parse the Response

Handle the JSON response with pagination metadata
4

Build Your Integration

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

​
Available Endpoints

The API provides read access to core FunnelFox data:

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
  • 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:
HeaderRequiredDescription
Fox-SecretYesYour project’s secret key
Content-TypeNoSet 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

  • 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
  • Check your filters aren’t too restrictive
  • Verify the resources exist in your project
  • Ensure you’re using the correct IDs
  • Use the exact cursor value from the previous response
  • Don’t modify or decode the cursor
  • Check has_more before requesting next page
  • 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