Forms

Forms capture contact data through embeddable or hosted form submissions.

List Forms

`GET /api/workspaces/{workspaceId}/forms`

Auth: Session required

Query Parameters:

Param	Type	Default	Description
`page`	number	1	Page number
`limit`	number	50	Items per page

Response:


{
  "data": [
    {
      "id": "frm_abc123",
      "name": "Newsletter Signup",
      "fields": [...],
      "doubleOptIn": false,
      "settings": {},
      "_count": { "submissions": 500 },
      "createdAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 10, "totalPages": 1 }
}

Create Form

`POST /api/workspaces/{workspaceId}/forms`

Auth: Session required

Request Body:


{
  "name": "Newsletter Signup",
  "fields": [
    { "name": "email", "type": "email", "label": "Email Address", "required": true },
    { "name": "firstName", "type": "text", "label": "First Name", "required": false },
    { "name": "interests", "type": "select", "label": "Interests", "options": ["tech", "marketing", "design"] }
  ],
  "settings": {
    "redirectUrl": "https://example.com/thank-you",
    "successMessage": "Thanks for signing up!"
  },
  "doubleOptIn": true
}

Field Definition

Field	Type	Required	Description
`name`	string	Yes	Field identifier (used as form key)
`type`	string	Yes	`text`, `email`, `number`, `select`, `textarea`, etc.
`label`	string	Yes	Display label
`required`	boolean	No	Whether field is required
`options`	string[]	No	Options for select/radio fields
`placeholder`	string	No	Placeholder text

Submit Form (Public)

`POST /api/forms/{formId}/submit`

Public endpoint for form submissions. CORS-enabled.

Auth: None required
Rate Limit: 10 requests per minute per IP + form combination

Request Body: Key-value pairs matching form field names.


{
  "email": "jane@example.com",
  "firstName": "Jane",
  "interests": "marketing"
}

Response (201):


{
  "success": true,
  "submissionId": "sub_abc123"
}

What Happens on Submit

Validates required fields
Creates or updates contact by email
Sets consent to OPTED_IN (unless double opt-in is enabled)
Fires form.submitted event
Triggers any campaigns with form-based triggers

Errors:

404 — Form not found
400 — Missing required fields
429 — Rate limited