Developers

REST API

Programmatic access to your workspace: contacts, submissions, events, test stats, workflow triggers and webhooks. Prefer an AI assistant doing the work? See the MCP documentation.

Authentication

Create an API key in the dashboard under API & webhooks (workspace admin role required; available on Pro and Scale plans). The token — fs_live_… — is shown once at creation; only its hash is stored. Send it as a Bearer token on every request:

curl https://app.funnelsplit.com/v1/contacts \
  -H "Authorization: Bearer fs_live_YOUR_TOKEN"

• Base URL: https://app.funnelsplit.com — all endpoints below are relative to it.
• All requests and responses are JSON (content-type: application/json).
• Keys are scoped (below) and can be revoked instantly from the dashboard.

Scopes

Each key carries an explicit set of scopes. A request needing a scope the key lacks gets 403 insufficient_scope.

Data API scopes

AI / content-control scopes (MCP)

These scopes power the MCP endpoint, which lets AI assistants build and manage content:

Errors & rate limits

• Error responses: { "error": "<code>", "message"?: "...", "details"?: [...] }.
• 401 unauthorized — missing, malformed, unknown or revoked token (indistinguishable by design).
• 403 insufficient_scope — key lacks the required scope; 403 plan_limit_exceeded — plan no longer includes the API.
• 400 invalid_body — validation failed; details lists the issues. 404 not_found — no such resource in your workspace.
• Rate limit: 120 requests/minute per key (shared between REST and MCP). Over-limit requests get 429 rate_limited with a Retry-After header (seconds).

Contacts

curl "https://app.funnelsplit.com/v1/contacts?search=jane&limit=10" \
  -H "Authorization: Bearer fs_live_…"

// 200
{ "contacts": [ { "id": "…", "email": "jane@acme.com", "fields": { "plan": "trial" }, "createdAt": "…" } ] }

curl -X POST https://app.funnelsplit.com/v1/contacts \
  -H "Authorization: Bearer fs_live_…" -H "content-type: application/json" \
  -d '{ "email": "jane@acme.com", "fields": { "company": "Acme", "plan": "trial" } }'

// 201
{ "contact": { "id": "…", "email": "jane@acme.com", "fields": { "company": "Acme", "plan": "trial" } } }

Submissions

{ "submissions": [ { "id": "…", "formId": "…", "contactId": "…", "data": { "f_fld_email": "jane@acme.com" }, "createdAt": "…" } ] }

Events

curl -X POST https://app.funnelsplit.com/v1/events \
  -H "Authorization: Bearer fs_live_…" -H "content-type: application/json" \
  -d '{ "name": "purchase", "fs_vid": "vid_from_cookie", "data": { "amount": 4900 } }'

Test stats

{ "test": { "id": "…", "name": "Hero copy", "status": "running", "mode": "fixed" },
  "variants": [ { "id": "…", "letter": "A", "name": "Control (live)", "isControl": true }, … ],
  "stats": { … } }

Workflow triggers

Inbound webhooks

Receive data from external systems (payment processors, CRMs). Create one under API & webhooks — you get a URL code and a signing secret. No API key is used; authentication is the HMAC signature.

// Node.js signature
const crypto = require('node:crypto');
const body = JSON.stringify({ email: 'jane@acme.com', fs_vid: 'vid_…' });
const signature = crypto.createHmac('sha256', HOOK_SECRET).update(body).digest('hex');

await fetch('https://app.funnelsplit.com/v1/hooks/in/YOUR_CODE', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'X-FS-Signature': signature },
  body,
});
// 202 { "accepted": true }

Outbound webhooks

Workflow outbound_webhook steps POST JSON to your URL with the same signature scheme in reverse:

• Header X-FS-Signature = hex HMAC-SHA256(your endpoint's secret, raw body) — verify it before trusting the payload.
• Non-2xx responses are retried 5× with exponential backoff (1 m → 2 m → 4 m → 8 m → 16 m), then marked dead — you can retry dead deliveries manually from the dashboard (Automate → Integrations → Webhook deliveries).
• Delivery timeout is 15 seconds; respond fast and process asynchronously.

Conversion pixel (external thank-you pages)

Record a test conversion from a thank-you page on any domain (ClickBank, carts, your own checkout). Create a custom_event goal on your test — the dashboard's test page shows a ready-made copy-paste snippet. It fires the event at your site's beacon endpoint (POST https://<your-site>/px/e, no API key needed — it's rate-limited and bot-filtered):

<script>
(function(){var h='https://YOUR-SITE.funnelsplit.com',q=new URLSearchParams(location.search),v=q.get('fsv');
try{if(v)localStorage.setItem('fs_vid',v);v=v||localStorage.getItem('fs_vid')}catch(e){}
if(!v){var m=document.cookie.match(/(?:^|; )fs_vid=([^;]*)/);v=m?m[1]:null}
var p=JSON.stringify({t:'custom',name:'EVENT_NAME',vid:v});
if(!(navigator.sendBeacon&&navigator.sendBeacon(h+'/px/e',p)))fetch(h+'/px/e',{method:'POST',body:p,mode:'no-cors',keepalive:true});
})();
</script>

• Cross-domain attribution: add data-fs-decorate to the CTA link on your FunnelSplit page — the page runtime appends ?fsv=<visitor-id> on click, and the pixel picks it up (and persists it in localStorage for multi-page funnels).
• Same-domain thank-you pages need nothing extra (the fs_vid cookie is read directly).
• Without a resolvable visitor id the event still counts for the workspace but cannot be attributed to a test variant. Safari may limit localStorage retention.