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
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.
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": true12 },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 }'
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": null18 }19 }20}
Comprehensive API documentation
Organized reference docs with real endpoint examples, response shapes, and code samples for every integration pattern.
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.
/api/v1/forms/api/v1/forms/api/v1/forms/{formId}/api/v1/forms/{formId}/api/v1/forms/{formId}/api/v1/forms/{formId}/responses/api/v1/forms/{formId}/responses/{responseId}/api/v1/forms/{formId}/webhooks/api/v1/forms/{formId}/webhooksSecure 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.
1// API Key authentication2fetch('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});910// Authorization: Bearer is also accepted11// 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.
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.
API Playground
Explore endpoints, build requests, and preview responses. See the request and response format for every API call.
/api/v1/formsx-api-key: your_api_key_here Content-Type: application/json Accept: application/json
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": 119 }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.
1// Cursor-based pagination2GET /api/v1/forms/2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a/responses3 ?cursor=MjAyNi0wMS0xNVQxMDozMDowMFp8YTFiMmMzZDQ4 &per_page=505 &sort=desc67// Response includes the next opaque cursor8{9 "success": true,10 "data": {11 "responses": [...],12 "pagination": {13 "per_page": 50,14 "next_cursor": "MjAyNi0wMS0xNVQxMDozNTowMFp8ZTVmNmE3Yjg"15 }16 }17}
1// Filter by submission date and sort direction2GET /api/v1/forms/2f6d8f08-6b99-4f7b-a7b9-2f3cd5e1028a/responses3 ?since=2026-01-01T00:00:00Z4 &until=2026-02-01T00:00:00Z5 &sort=asc6 &per_page=2578// 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.
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 TransitAll API traffic is encrypted in transit with TLS. HSTS enforced across all endpoints.
1# All API requests use HTTPS2$ 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 ControlAPI 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 header2fetch('https://wittyform.com/api/v1/forms', {3 headers: {4 'x-api-key': 'your_api_key_here',5 },6});
HMAC Webhook Signatures
WebhooksWebhook 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 = crypto4 .createHmac('sha256', webhookSecret)5 .update(req.body)6 .digest('hex');7const valid = sig === `sha256=${expected}`;
Rate Limiting
ProtectionEvery 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 response2X-RateLimit-Remaining: 953X-RateLimit-Reset: 17098128004Retry-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 / SvelteUse WittyForm as a headless backend. Build your own form UI with any framework, submit data via API, and let WittyForm handle storage and notifications.
1// Submit from your custom React form2async 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 );2021 const result = await response.json();22 // Webhooks fire automatically23 return result.data.response.id;24}
Custom Analytics Dashboard
Business IntelligencePull form responses into your own dashboard. Build custom reports, charts, and KPIs using data from the API.
1// Fetch responses for a form2const 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);1011const payload = await response.json();12const { responses, pagination } = payload.data;1314// Process responses for your dashboard15const analytics = {16 totalResponses: pagination.total,17 recentSubmissions: responses.length,18 // Build your own metrics from the data19};
Automated Workflows
Webhooks + IntegrationsUse webhooks to trigger automated workflows when forms are submitted. Connect to Slack, Google Sheets, CRMs, or any service that accepts HTTP requests.
1// Your webhook endpoint receives submissions2app.post('/webhooks/wittyform', (req, res) => {3 const { event, data } = req.body;45 if (event === 'form.submitted') {6 // Forward to Slack7 notifySlack(data.answers);89 // Add to your CRM10 createContact(data.answers.email, data.answers.name);1112 // Append to Google Sheet13 appendToSheet(data.answers);14 }1516 res.status(200).send('OK');17});
Explore Related Features
Got questions?
Everything you need to know about WittyForm. Can't find what you're looking for? Contact Support