Forms API

Create, manage, and configure forms. Forms are defined by JSON schemas that specify fields, validation rules, and behavior.

Create Form

POST /forms

Creates a new form. Requires authentication with a secret key or session token.

Request Body

{
  "title": "Contact Form",
  "status": "live" | "draft" | "archived",
  "environment": "production" | "development" | "staging",
  "fields": [
    {
      "id": "name",
      "type": "text" | "email" | "select" | "textarea" | "number" | "date" | "file",
      "label": "Your Name",
      "required": true,
      "placeholder": "Enter your name",
      "validate": {
        "minLength": 2,
        "maxLength": 100,
        "pattern": "^[a-zA-Z ]+$"
      },
      "options": ["Option 1", "Option 2"], // For select fields
      "pii": false
    }
  ],
  "allowedOrigins": ["https://example.com"],
  "fieldPolicies": {
    "email": "encrypted",
    "ssn": "masked"
  },
  "storage": {
    "mode": "owner" | "platform",
    "bucket": "my-bucket",
    "region": "us" | "eu" | "global"
  },
  "ui": {
    "theme": "auto" | "light" | "dark",
    "progress": "steps" | "bar" | "none",
    "layout": "one-by-one" | "all-at-once"
  },
  "spamProtection": {
    "honeypot": {
      "enabled": true,
      "fieldName": "website"
    },
    "recaptcha": {
      "enabled": true,
      "siteKey": "your-site-key",
      "threshold": 0.5
    }
  },
  "webhooks": [
    {
      "event": "response.created",
      "url": "https://example.com/webhook",
      "secret": "webhook-secret"
    }
  ],
  "retention": {
    "days": 90,
    "policy": "delete" | "archive"
  }
}

Response

{
  "id": "form_123",
  "title": "Contact Form",
  "status": "live",
  "environment": "production",
  "fields": [...],
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

List Forms

GET /forms

Lists all forms in the current environment. Supports query parameters for filtering.

Query Parameters

status - Filter by status (live, draft, archived)
environment - Filter by environment
limit - Number of results (default: 50)
offset - Pagination offset

Get Form

GET /forms/{id}

Retrieves a specific form by ID. Use /forms/{id}/public to get the public schema for embedding.

Update Form

PUT /forms/{id}

Updates an existing form. Send only the fields you want to update.

Delete Form

DELETE /forms/{id}

Permanently deletes a form and all associated submissions.

Field Types

text

Single-line text input. Supports validation with minLength, maxLength, and pattern (regex).

email

Email input with automatic validation. Supports the same validation options as text.

textarea

Multi-line text input. Supports minLength and maxLength validation.

select

Dropdown select. Requires an options array with available choices.

number

Numeric input. Supports min and max validation.

date

Date picker input.

file

File upload. Requires signed URL generation via the uploads API.

Submissions API →Webhooks →