API Documentation

Everything you need to integrate Zapforms into your applications.

Introduction

The Zapforms API provides programmatic access to your forms and submissions. Every form you create automatically gets a REST API endpoint that you can use to submit data and retrieve submissions.

RESTful Design

Standard HTTP methods and status codes

JSON Responses

All responses are in JSON format

Rate Limited

Fair usage limits to prevent abuse

Quick Start

1. Get your API Key

Navigate to the API Keys section in your dashboard to generate a new API key.

Manage API Keys

2. Make your first request

Use your API key to authenticate and list your forms:

curl -X GET https://zapforms.io/api/v1/forms \
  -H "X-API-Key: zf_your_api_key_here"

3. Submit form data

Submit data to one of your forms:

curl -X POST https://zapforms.io/api/v1/forms/YOUR_FORM_ID/submit \
  -H "X-API-Key: zf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "email": "john@example.com"}'

Base URL

https://zapforms.io/api/v1

All API endpoints are relative to this base URL. The current API version is v1.

Authentication

API Key Authentication

All API requests require authentication using an API key

Include your API key in the request header:

X-API-Key: zf_your_api_key_here

API keys are prefixed with zf_ for easy identification. Keep your API keys secure and never expose them in client-side code.

Example authenticated request:

curl -X GET https://zapforms.io/api/v1/forms \
  -H "X-API-Key: zf_your_api_key_here"

Endpoints

List Forms

Get all forms associated with your account

GET

/api/v1/forms

Returns a paginated list of all your forms

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (max: 100, default: 20)
`active`	boolean	Filter by active status

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Contact Form",
      "slug": "contact-form",
      "description": "Main contact form",
      "fieldCount": 5,
      "isActive": true,
      "submissionCount": 42,
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "hasMore": false
  },
  "requestId": "req_1234567890_abc123"
}

List Submissions

Get all submissions for a specific form

GET

/api/v1/forms/{formId}/submissions

Returns a paginated list of form submissions

Path Parameters:

Parameter	Type	Description
`formId`	uuid	The ID of the form

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (max: 100, default: 20)
`from`	datetime	Filter submissions from this date
`to`	datetime	Filter submissions to this date

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "formId": "550e8400-e29b-41d4-a716-446655440000",
      "data": {
        "name": "John Doe",
        "email": "john@example.com",
        "message": "Hello, I'd like to learn more..."
      },
      "metadata": {
        "ip": "192.168.1.1",
        "userAgent": "Mozilla/5.0...",
        "submittedAt": "2025-01-25T10:30:00Z"
      },
      "createdAt": "2025-01-25T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "hasMore": true
  },
  "requestId": "req_1234567890_def456"
}

Get Submission

Retrieve a specific submission by ID

GET

/api/v1/forms/{formId}/submissions/{submissionId}

Returns a single submission

Path Parameters:

Parameter	Type	Description
`formId`	uuid	The ID of the form
`submissionId`	uuid	The ID of the submission

Submit Form

Submit data to a form via API

POST

/api/v1/forms/{formId}/submit

Submit data to a form

This endpoint can be used with or without authentication. Public form submissions don't require an API key.

Request Body:

The request body should contain the form field values as a JSON object.

{
  "name": "John Doe",
  "email": "john@example.com",
  "company": "Acme Inc",
  "message": "I'd like to learn more about your services"
}

Example Request:

curl -X POST https://zapforms.io/api/v1/forms/YOUR_FORM_ID/submit \
  -H "X-API-Key: zf_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "message": "Hello!"
  }'

Success Response:

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "message": "Form submitted successfully"
  },
  "requestId": "req_1234567890_ghi789"
}

Delete Submission

Delete a specific submission

DELETE

/api/v1/forms/{formId}/submissions/{submissionId}

Permanently delete a submission

This action is permanent and cannot be undone.

Path Parameters:

Parameter	Type	Description
`formId`	uuid	The ID of the form
`submissionId`	uuid	The ID of the submission to delete

Response Format

Success Response

All successful responses follow this structure

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    // Pagination metadata (if applicable)
    "page": 1,
    "limit": 20,
    "total": 100,
    "hasMore": true
  },
  "requestId": "req_1234567890_abc123"
}

Error Response

All error responses follow this structure

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error details (if applicable)
    }
  },
  "status": 400,
  "requestId": "req_1234567890_xyz789"
}

Error Codes

Common Error Codes

List of all possible error codes and their meanings

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Authentication required
`INVALID_API_KEY`	401	Invalid or expired API key
`FORBIDDEN`	403	Access denied to resource
`NOT_FOUND`	404	Resource not found
`FORM_NOT_FOUND`	404	Form does not exist
`SUBMISSION_NOT_FOUND`	404	Submission does not exist
`FORM_INACTIVE`	403	Form is not accepting submissions
`VALIDATION_ERROR`	400	Request validation failed
`INVALID_REQUEST`	400	Invalid request format
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`SPAM_DETECTED`	403	Submission flagged as spam
`INTERNAL_ERROR`	500	Internal server error
`DATABASE_ERROR`	500	Database operation failed

Rate Limiting

Rate Limits

API rate limits are enforced per API key

Free Plan

100

requests per minute

Pro Plan

1,000

requests per minute

Rate Limit Headers:

Every API response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds until you can retry (only on 429)

When you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait for the time specified in the Retry-After header before retrying.

Pagination

Paginating Results

List endpoints return paginated results

Use the page and limit query parameters to navigate through results:

GET /api/v1/forms?page=2&limit=50

Pagination Metadata:

All paginated responses include metadata in the response:

{
  "meta": {
    "page": 2,        // Current page
    "limit": 50,      // Items per page
    "total": 234,     // Total items available
    "hasMore": true   // More pages available
  }
}

The maximum limit per page is 100 items. Requesting more will default to 100.

Webhooks

Real-time Event Notifications

Receive instant notifications when events occur in your forms

Webhooks allow you to receive real-time HTTP POST requests when specific events occur:

Supported Events:

submission.createdNew submission received
submission.updatedSubmission modified
submission.deletedSubmission removed

Webhook Payload Example:

{
  "event": "submission.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "sub_abc123",
    "form_id": "frm_xyz789",
    "created_at": "2025-01-15T10:30:00Z",
    "fields": {
      "name": "John Doe",
      "email": "john@example.com",
      "message": "Hello world!"
    }
  }
}

Security & Verification:

All webhook requests include an HMAC-SHA256 signature in the X-Webhook-Signature header for verification:

// Verify webhook signature
const crypto = require('crypto');

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

Configure webhooks in your form settings. Each webhook supports custom headers, retry logic with exponential backoff, and delivery logs for debugging.

Available NowFree: 1 webhook/formPro: Unlimited webhooks

Need help? Contact support at support@zapforms.io

Back to Dashboard

Getting Started

Authentication

Endpoints

Concepts

API Documentation

Introduction

Quick Start

Base URL

Authentication

Example authenticated request:

Endpoints

Query Parameters:

Example Response:

Path Parameters:

Query Parameters:

Example Response:

Path Parameters:

Request Body:

Example Request:

Success Response:

Path Parameters:

Response Format

Error Codes

Rate Limiting

Rate Limit Headers:

Webhooks

Supported Events:

Webhook Payload Example:

Security & Verification: