Developer API

Build anything with the WittyForm API.

A complete REST API with real-time webhooks and flexible authentication. Create forms, collect responses, and automate workflows programmatically.

No credit card · Unlimited forms · 5 min setup

14-day money-backNo subscriptions

One request. Your form is created.

Create a draft form with a single API call. The response returns the canonical form record, ready for you to configure and publish.

POST /api/v1/forms
Request
1curl -X POST "https://wittyform.com/api/v1/forms" \
2 -H "x-api-key: your_api_key_here" \
3 -H "Content-Type: application/json" \
4 -d '{
5 "title": "Contact Form",
6 "description": "Main website contact form",
7 "fields": [
8 {
9 "type": "email",
10 "label": "Work Email",
11 "required": true
12 },
13 {
14 "type": "textarea",
15 "label": "How can we help?",
16 "placeholder": "Tell us about your project..."
17 }
18 ],
19 "settings": {
20 "redirect_url": "https://example.com/thanks"
21 }
22 }'
Response
201 Created
1{
2 "success": true,
3 "data": {
4 "form": {
5 "id": "2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a",
6 "title": "Contact Form",
7 "description": "Main website contact form",
8 "status": "draft",
9 "fields": [
10 { "type": "email", "label": "Work Email", "required": true },
11 { "type": "textarea", "label": "How can we help?" }
12 ],
13 "settings": { "redirect_url": "https://example.com/thanks" },
14 "short_id": "8x7hK2mN",
15 "created_at": "2026-01-15T10:30:00Z",
16 "updated_at": "2026-01-15T10:30:00Z",
17 "published_at": null
18 }
19 }
20}

Comprehensive API documentation

Organized reference docs with real endpoint examples, response shapes, and code samples for every integration pattern.

wittyform.com/docs/api
Search documentation.../

Authentication & API Keys

Generate keys and authenticate requests with the x-api-key header

Base URL & Versioning

All endpoints are versioned under https://wittyform.com/api/v1/

Rate Limits & Quotas

1,000 requests/min on Pro, 5,000/min on Enterprise, with X-RateLimit headers in every response

Every endpoint you need

Full CRUD operations for forms and responses, plus webhook triggers. Clean RESTful design with predictable resource URLs.

Forms5 endpoints
GET/api/v1/forms
POST/api/v1/forms
GET/api/v1/forms/{formId}
PUT/api/v1/forms/{formId}
DELETE/api/v1/forms/{formId}
Responses2 endpoints
GET/api/v1/forms/{formId}/responses
GET/api/v1/forms/{formId}/responses/{responseId}
Webhooks2 endpoints
GET/api/v1/forms/{formId}/webhooks
POST/api/v1/forms/{formId}/webhooks

Secure by default

Two authentication methods to fit your integration pattern. Use API keys for server-to-server calls, or session auth for browser-based access.

API Key Authentication

Generate your API key from the dashboard and pass it via the x-api-key header. Simple, secure, and designed for server-to-server calls.

Session Authentication

For browser-based access, Clerk session cookies authenticate requests automatically. The API supports hybrid auth, trying API key first and falling back to session.

All traffic encrypted in transit with TLS. API keys validated with timing-safe comparison.
authentication.js
1// API Key authentication
2fetch('https://wittyform.com/api/v1/forms', {
3 method: 'GET',
4 headers: {
5 'x-api-key': 'your_api_key_here',
6 'Content-Type': 'application/json',
7 },
8});
9
10// Authorization: Bearer is also accepted
11// headers: { 'Authorization': 'Bearer your_api_key_here' }

Real-time webhooks

Get notified instantly when a form is submitted. JSON payloads delivered to your endpoint when events happen.

Form Submitted
Webhook Fires
Your Server Receives JSON
Webhook Payload
On submission
1{
2 "event": "form.submitted",
3 "timestamp": "2026-01-15T10:30:00Z",
4 "data": {
5 "formId": "2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a",
6 "responseId": "a1b2c3d4-09f7-4a6d-8df0-1de9f68015b2",
7 "answers": {
8 "email": "[email protected]",
9 "name": "Jane Cooper",
10 "message": "Interested in Enterprise plan"
11 },
12 "submittedVia": "api"
13 },
14 "formId": "2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a"
15}

Rate limits and performance

Rate limiting powered by Upstash Redis for reliable request tracking. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers so you always know where you stand.

1,000
API calls/min (Pro)
5,000
API calls/min (Enterprise)
30
Form creates/hr
3x
Auto Retry on Failure
Interactive

API Playground

Explore endpoints, build requests, and preview responses. See the request and response format for every API call.

api-playground
Try it
Endpoints
GET/api/v1/forms
Headers
x-api-key: your_api_key_here
Content-Type: application/json
Accept: application/json
Body
No body
Response
200 OK38ms
1{
2 "success": true,
3 "data": {
4 "forms": [
5 {
6 "id": "2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a",
7 "title": "Contact Form",
8 "status": "published",
9 "fields": [],
10 "settings": {},
11 "created_at": "2026-01-15T10:30:00Z"
12 }
13 ],
14 "pagination": {
15 "total": 12,
16 "page": 1,
17 "per_page": 25,
18 "total_pages": 1
19 }
20 }
21}

Powerful filtering and pagination

Cursor-based pagination stays consistent at scale. Date-range and sort parameters let you retrieve the response window you need without loading everything.

Cursor Pagination
1// Cursor-based pagination
2GET /api/v1/forms/2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a/responses
3 ?cursor=MjAyNi0wMS0xNVQxMDozMDowMFp8YTFiMmMzZDQ
4 &per_page=50
5 &sort=desc
6
7// Response includes the next opaque cursor
8{
9 "success": true,
10 "data": {
11 "responses": [...],
12 "pagination": {
13 "per_page": 50,
14 "next_cursor": "MjAyNi0wMS0xNVQxMDozNTowMFp8ZTVmNmE3Yjg"
15 }
16 }
17}
Query Filters
1// Filter by submission date and sort direction
2GET /api/v1/forms/2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a/responses
3 ?since=2026-01-01T00:00:00Z
4 &until=2026-02-01T00:00:00Z
5 &sort=asc
6 &per_page=25
7
8// Without a cursor, add page=2 (or another page number)
9// to use offset pagination with total/page metadata.

Error handling reference

Every error response follows a consistent JSON format with machine-readable codes and human-readable messages.

Consistent error format

Every error includes a machine-readable code and a message safe to display to end users. Rate limit errors include retryAfter in seconds.

Security built in

Multiple layers of protection for your data and integrations. Every request is encrypted, authenticated, and rate limited.

TLS Encryption

In Transit

All API traffic is encrypted in transit with TLS. HSTS enforced across all endpoints.

1# All API requests use HTTPS
2$ curl -v https://wittyform.com/api/v1/forms 2>&1 \
3 | grep "SSL connection"
4> SSL connection using TLSv1.3

Timing-Safe Key Validation

Access Control

API keys are validated using timing-safe comparison to prevent timing attacks. Keys are never logged or exposed in error messages.

1// API key passed via header
2fetch('https://wittyform.com/api/v1/forms', {
3 headers: {
4 'x-api-key': 'your_api_key_here',
5 },
6});

HMAC Webhook Signatures

Webhooks

Webhook payloads are signed with HMAC-SHA256 using your webhook secret. Verify signatures server-side to ensure authenticity.

1const crypto = require('crypto');
2const sig = req.headers['x-webhook-signature'];
3const expected = crypto
4 .createHmac('sha256', webhookSecret)
5 .update(req.body)
6 .digest('hex');
7const valid = sig === `sha256=${expected}`;

Rate Limiting

Protection

Every endpoint is rate limited via Upstash Redis. Rate limit headers are included in every response so you can monitor usage proactively.

1// Rate limit headers in every response
2X-RateLimit-Remaining: 95
3X-RateLimit-Reset: 1709812800
4Retry-After: 30 // only on 429 responses

Built by developers, for developers

Three common integration patterns to get you started. Use the REST API directly with fetch or any HTTP client.

Headless Form Backend

React / Vue / Svelte

Use WittyForm as a headless backend. Build your own form UI with any framework, submit data via API, and let WittyForm handle storage and notifications.

Architecture
Your Frontend
WittyForm API
Storage + Webhooks
Get started
example.js
1// Submit from your custom React form
2async function handleSubmit(data) {
3 const response = await fetch(
4 'https://wittyform.com/api/v1/forms/2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a/responses',
5 {
6 method: 'POST',
7 headers: {
8 'x-api-key': 'your_api_key_here',
9 'Content-Type': 'application/json',
10 },
11 body: JSON.stringify({
12 answers: {
13 email: data.get('email'),
14 name: data.get('name'),
15 message: data.get('message'),
16 },
17 }),
18 }
19 );
20
21 const result = await response.json();
22 // Webhooks fire automatically
23 return result.data.response.id;
24}

Custom Analytics Dashboard

Business Intelligence

Pull form responses into your own dashboard. Build custom reports, charts, and KPIs using data from the API.

Architecture
WittyForm API
Your Backend
Custom Dashboard
Get started
example.js
1// Fetch responses for a form
2const response = await fetch(
3 'https://wittyform.com/api/v1/forms/2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a/responses?per_page=50',
4 {
5 headers: {
6 'x-api-key': 'your_api_key_here',
7 },
8 }
9);
10
11const payload = await response.json();
12const { responses, pagination } = payload.data;
13
14// Process responses for your dashboard
15const analytics = {
16 totalResponses: pagination.total,
17 recentSubmissions: responses.length,
18 // Build your own metrics from the data
19};

Automated Workflows

Webhooks + Integrations

Use webhooks to trigger automated workflows when forms are submitted. Connect to Slack, Google Sheets, CRMs, or any service that accepts HTTP requests.

Architecture
Form Submission
Webhook
Your Workflow
Get started
example.js
1// Your webhook endpoint receives submissions
2app.post('/webhooks/wittyform', (req, res) => {
3 const { event, data } = req.body;
4
5 if (event === 'form.submitted') {
6 // Forward to Slack
7 notifySlack(data.answers);
8
9 // Add to your CRM
10 createContact(data.answers.email, data.answers.name);
11
12 // Append to Google Sheet
13 appendToSheet(data.answers);
14 }
15
16 res.status(200).send('OK');
17});
FAQ

Got questions?

Everything you need to know about WittyForm. Can't find what you're looking for? Contact Support

$37 · paid once

Ready to Build Custom Integrations With Our API?

Start free and keep the five forms for good, or pay once and unlock all of it — unlimited forms, ten team members, AI, CRM, white label and the API. No renewal, ever.

14-day money-backInstant accessNo subscription, ever
Developer REST API & SDKs