Forms API

Create, read, update, and delete forms programmatically.

Management endpoints (GET list, POST, PUT, DELETE) require API key authentication. Public endpoints (GET single, token, submit) are accessible without authentication.

GET/api/forms

List all forms

Returns a paginated list of forms for the authenticated user. Requires API key.

Response

JSON

{
  "forms": [
    {
      "id": "form_abc123",
      "title": "Contact Form",
      "description": "Get in touch with us",
      "published": true,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "plan": "pro",
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

POST/api/forms

Create a form

Creates a new form with the specified configuration. Requires API key.

Request body

JSON

{
  "title": "Contact Form",
  "description": "Get in touch with us",
  "questions": [
    {
      "id": "q1",
      "type": "short_text",
      "title": "Your name",
      "required": true
    },
    {
      "id": "q2",
      "type": "email",
      "title": "Email address",
      "required": true
    },
    {
      "id": "q3",
      "type": "long_text",
      "title": "Message",
      "required": false
    }
  ],
  "theme": {
    "primaryColor": "#000000",
    "backgroundColor": "#ffffff"
  }
}

Response

JSON

{
  "id": "form_abc123",
  "title": "Contact Form",
  "published": false,
  "created_at": "2025-01-15T10:30:00Z"
}

GET/api/forms/:id

Get a form

Returns the full form configuration. Published forms are publicly accessible.

Response

JSON

{
  "id": "form_abc123",
  "title": "Contact Form",
  "description": "Get in touch with us",
  "published": true,
  "questions": [...],
  "theme": {...},
  "embed_settings": {...},
  "allowed_domains": ["example.com"]
}

PUT/api/forms/:id

Update a form

Update form configuration. Requires API key and form ownership.

Request body

JSON

{
  "title": "Updated Contact Form",
  "published": true
}

Response

JSON

{
  "id": "form_abc123",
  "title": "Updated Contact Form",
  "published": true,
  "updated_at": "2025-01-15T11:00:00Z"
}

DELETE/api/forms/:id

Delete a form

Permanently deletes a form and all its responses. Requires API key.

Response

JSON

{ "success": true }

Public submission endpoints

These endpoints are used by the embed SDK and don't require API key authentication. Instead, they use short-lived tokens for security.

GET/api/forms/:id/token

Get embed token

Issues a signed token required for form submissions. Tokens expire after 30 minutes.

Response

JSON

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expiresIn": 1800
}

POST/api/forms/:id/submit

Submit a response

Submit form answers. Requires a valid embed token. Used by the embed SDK.

Request body

JSON

{
  "answers": {
    "q1": "John Doe",
    "q2": "john@example.com",
    "q3": "Hello, I have a question..."
  },
  "_token": "eyJhbGciOiJIUzI1NiIs...",
  "fingerprint": "abc123...",
  "clientMetadata": {
    "screenWidth": 1920,
    "screenHeight": 1080,
    "language": "en-US",
    "pageUrl": "https://example.com/contact"
  }
}

Response

JSON

{
  "success": true,
  "responseId": "resp_xyz789"
}

Form blocks

See the Form Blocks reference for detailed settings and subtypes.

short_textFree

long_textFree

emailFree

numberFree

phoneFree

urlFree

dateFree

date_rangeFree

contactFree

multiple_choiceFree

dropdownFree

yes_noFree

color_pickerFree

ratingFree

star_ratingFree

number_ratingFree

sliderFree

rankingFree

videoPro

signaturePro

file_uploadPro

paymentPro

text_blockFree

consentFree

hiddenFree

Error responses

form_not_found404Form does not exist

form_not_published403Form is not accepting responses

form_closed403Form closed by date or response limit

domain_not_allowed403Submission from unauthorized domain

invalid_token403Missing or expired embed token

duplicate_submission400User already submitted (Pro+)

rate_limited429Too many submissions from this IP

← API Overview Polls API →