API Reference

API Documentation

Complete reference for the zForms SDK and REST API.

Initialization

Setup & config

Tracking API

Track forms & events

REST API

Server-side API

Webhooks

Real-time events

Initialization

Constructor

new ZFormsTracker(config: TrackerConfig)

Parameters

NameTypeRequiredDescription

projectIdstringYesYour project ID from dashboard

apiKeystringYesYour API key from dashboard

trackPageViewsbooleanNoAuto-track page views (default: true)

anonymizeIPbooleanNoAnonymize IP addresses (default: true)

enableAIbooleanNoEnable AI insights (default: true)

const tracker = new ZFormsTracker({
  projectId: 'proj_abc123',
  apiKey: 'zf_sk_xyz789',
  trackPageViews: true,
  anonymizeIP: true,
  enableAI: true
});

Tracking Methods

trackForm()

Start tracking a form element.

tracker.trackForm(selector: string, options?: FormTrackingOptions)

Parameters

selectorCSS selector for the form element

options.nameOptional form name for identification

options.categoryOptional category (e.g., 'lead-gen', 'checkout')

options.multiStepEnable multi-step form tracking

tracker.trackForm('#signup-form', {
  name: 'User Signup',
  category: 'authentication',
  multiStep: false
});

track()

Track a custom event.

tracker.track(eventName: string, properties?: Record<string, any>)

tracker.track('form_submitted', {
  formId: 'contact-form',
  fields: 5,
  timeToComplete: 45
});

identify()

Associate events with a user.

tracker.identify(userId: string, traits?: Record<string, any>)

tracker.identify('user_123', {
  email: 'user@example.com',
  plan: 'pro'
});

stopTracking()

Stop tracking a specific form.

tracker.stopTracking(selector: string)

tracker.stopTracking('#contact-form');

REST API

Base URL: https://api.zforms.xyz/v1

Authentication: Include your API key in the X-API-Key header

GET /projects

List all your projects.

curl -X GET https://api.zforms.xyz/v1/projects \
  -H "X-API-Key: your_api_key"

Response (200 OK)

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "My Website",
      "domain": "example.com",
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ]
}

GET /analytics/:projectId

Get analytics data for a project.

curl -X GET https://api.zforms.xyz/v1/analytics/proj_abc123 \
  -H "X-API-Key: your_api_key" \
  -d "startDate=2025-01-01" \
  -d "endDate=2025-01-31"

Response (200 OK)

{
  "sessions": 1234,
  "submissions": 567,
  "conversionRate": 45.9,
  "avgTimeToComplete": 125,
  "topDropoffFields": [
    { "field": "email", "dropoffRate": 12.3 }
  ]
}

POST /events

Send a custom event (server-side tracking).

curl -X POST https://api.zforms.xyz/v1/events \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "proj_abc123",
    "event": "form_submitted",
    "properties": {
      "formId": "contact-form"
    }
  }'

Webhooks

Receive real-time notifications when events occur in your forms. Configure webhooks in your dashboard under Project Settings.

Available Events

form.submittedWhen a form is successfully submitted
form.abandonedWhen a user abandons a form
insight.generatedWhen AI generates a new insight

Webhook Payload Example

{
  "event": "form.submitted",
  "timestamp": "2025-01-30T14:23:45Z",
  "projectId": "proj_abc123",
  "data": {
    "formId": "contact-form",
    "sessionId": "sess_xyz789",
    "timeToComplete": 125,
    "fieldsCompleted": 5
  }
}

Webhook Security

All webhook requests include a signature in the X-ZForms-Signature header. Verify this signature to ensure requests are from zForms.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return digest === signature;
}

Rate Limits

Free Plan

1,000

events per month

Pro Plan

100,000

events per month

Enterprise

Unlimited

custom rate limits

API requests are limited to 100 requests per minute per API key. Exceeding this limit will result in a 429 Too Many Requests response.

Official SDKs

JavaScript / TypeScript

npm install @zforms/tracker

React

npm install @zforms/react

Python

pip install zforms

Node.js

npm install @zforms/node

Need an SDK for a different language? Contact us to request support.