Forms

Overview

The Forms API provides endpoints for creating, reading, updating, and deleting forms. Forms are the central entity in the system and define the structure, validation, and behavior of data collection.

Endpoints

Create Form

Create a new form in a specified environment.

Endpoint: POST /forms

Authentication: Required (Session token)

Request Body:

{
  "title": "Contact Form",
  "environment": "development",
  "status": "draft",
  "fields": [
    {
      "id": "name",
      "type": "text",
      "label": "Your Name",
      "required": true
    },
    {
      "id": "email",
      "type": "email",
      "label": "Email Address",
      "required": true,
      "pii": true
    }
  ],
  "ui": {
    "theme": "auto",
    "progress": "steps",
    "layout": "one-by-one"
  },
  "storage": {
    "mode": "owner"
  }
}

Response: 201 Created

{
  "id": "form_123",
  "version": 1,
  "title": "Contact Form",
  "status": "draft",
  "userId": "user_456",
  "environment": "development",
  "workspaceEnvironment": "development",
  "fields": [...],
  "publishableKey": "pk-live-...",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Error Responses:

• 400: Invalid environment name or missing required fields

• 401: Unauthorized

• 404: Environment does not exist

---

List Forms

List all forms for the authenticated user in a specified environment.

Endpoint: GET /forms?environment={environment}

Authentication: Optional (public access if not authenticated)

Query Parameters:

• environment (required): Environment name

Response: 200 OK

{
  "items": [
    {
      "id": "form_123",
      "title": "Contact Form",
      "status": "live",
      ...
    }
  ]
}

Error Responses:

• 400: Environment parameter missing or invalid

---

Get Form

Retrieve a specific form by ID.

Endpoint: GET /forms/{id}?environment={environment}

Authentication: Optional (public access for live forms)

Path Parameters:

• id (required): Form ID

Query Parameters:

• environment (optional): Environment name for validation

Response: 200 OK

{
  "id": "form_123",
  "version": 1,
  "title": "Contact Form",
  "status": "live",
  "fields": [...],
  ...
}

Response Headers:

• ETag: Form version (for caching)

Error Responses:

• 400: Invalid environment name

• 403: Forbidden (form not in specified environment)

• 404: Form not found

---

Get Public Form

Retrieve a form schema for public embedding (no authentication required).

Endpoint: GET /v1/forms/{formId}/public

Authentication: Not required

Path Parameters:

• formId (required): Form ID

Response: 200 OK

{
  "id": "form_123",
  "title": "Contact Form",
  "fields": [...],
  "ui": {...},
  ...
}

Note: Only returns forms with status: "live"

---

Update Form

Update an existing form. Creates a new version automatically.

Endpoint: PUT /forms/{id}?environment={environment}

Authentication: Required (Session token)

Path Parameters:

• id (required): Form ID

Query Parameters:

• environment (optional): Environment name for validation

Request Body:

{
  "title": "Updated Contact Form",
  "fields": [...],
  "status": "live"
}

Response: 200 OK

{
  "id": "form_123",
  "version": 2,
  "title": "Updated Contact Form",
  "status": "live",
  ...
}

Error Responses:

• 400: Invalid environment name or request body

• 401: Unauthorized

• 403: Forbidden (not form owner)

• 404: Form not found

Note:

• Version is automatically incremented

• Cannot change userId or environment

• updatedAt is automatically set

---

Delete Form

Delete a form.

Endpoint: DELETE /forms/{id}?environment={environment}

Authentication: Required (Session token)

Path Parameters:

• id (required): Form ID

Query Parameters:

• environment (optional): Environment name for validation

Response: 204 No Content

Error Responses:

• 400: Invalid environment name

• 401: Unauthorized

• 403: Forbidden (not form owner)

• 404: Form not found

---

Form Schema Reference

Required Fields

• title: Form title (string)

• environment: Workspace environment (string)

• fields: Array of form fields (array)

Optional Fields

• id: Form ID (auto-generated if not provided)

• status: Form status (draft, live, archived, active, disabled)

• ui: UI configuration object

• storage: Storage configuration object

• logic: Conditional logic rules

• retention: Data retention policy

• webhooks: Webhook configurations

• notifications: Email notification settings

• autoResponse: Auto-response configuration

• spamProtection: Spam protection settings

Field Types

• text: Single-line text input

• email: Email input with validation

• textarea: Multi-line text input

• select: Dropdown selection

• number: Numeric input

• date: Date picker

• file: File upload

Field Configuration

{
  "id": "field_id",
  "type": "text",
  "label": "Field Label",
  "required": true,
  "placeholder": "Enter value",
  "validate": {
    "minLength": 2,
    "maxLength": 100,
    "pattern": "^[A-Za-z]+$"
  },
  "pii": false,
  "showIf": {
    "otherField": "value"
  }
}

Examples

Create a Simple Contact Form

curl -X POST https://api.formr.xyz/forms \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Contact Form",
    "environment": "development",
    "fields": [
      {
        "id": "name",
        "type": "text",
        "label": "Name",
        "required": true
      },
      {
        "id": "email",
        "type": "email",
        "label": "Email",
        "required": true,
        "pii": true
      },
      {
        "id": "message",
        "type": "textarea",
        "label": "Message",
        "required": true
      }
    ]
  }'

Update Form Status

curl -X PUT https://api.formr.xyz/forms/form_123?environment=development \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "live"
  }'

Next Steps

• API Reference - API overview

• Submissions API - Submit forms and retrieve responses

• Dashboard Guide - Use the dashboard