Forms

Overview

Forms are reusable field collections belonging to a company. They are used by activations, ticket types, and other features. The API supports listing, creating, and updating forms and their fields. Subscription: All plans, including Free.

Form field types

Field type values fall into two categories:

Custom fields

General-purpose fields you can add freely to any form. Use the type value in the API when creating or updating fields.

Type	Label	Description
`text`	Text	Single-line text input. Supports `placeholder`.
`textarea`	Multi-line text	Multi-line text input. Supports `placeholder`.
`number`	Number	Numeric input. Supports `placeholder`, `min`, and `max`.
`date`	Date	Date picker.
`time`	Time	Time picker.
`url`	URL	URL input. Supports `placeholder`.
`file`	File	File upload.
`option`	Options	Multiple-choice field. Requires an `options` array.
`select`	Select box	Dropdown selection. Requires an `options` array.
`toggle`	Toggle	On/off switch. Does not support `description`.
`rating`	Rating	Star or scale rating input.

Common fields

Pre-defined field types that map to standard lead attributes (birthdate, phone, job title, etc.). Each common field type can appear at most once per form — adding a second field with the same common type returns a validation error.

Type	Label	Description
`birthdate`	Birthdate	Date of birth.
`company_name`	Company name	Attendee’s company name.
`company_url`	Company URL	Company website URL.
`consent`	Marketing Consent	Consent checkbox. Does not support `description` (use `label` for consent text). Label max 10,000 characters.
`country`	Country	Country selection.
`gender`	Gender	Gender selection.
`job_title`	Job title	Job title or role.
`language`	Language	Preferred language.
`phone`	Phone number	Phone number input.
`social_url`	Social URL	Social profile URL. Supports `placeholder`.

Field attributes by type

Attribute	Supported on
`description`	All types except `consent` and `toggle`
`placeholder`	`text`, `textarea`, `number`, `url`, `social_url`
`required`	All types
`min` / `max`	`number` only
`options`	`option` and `select` — see Options format
`position`	All types (sort order, >= 0)

Options format

For option and select fields, options accepts:

A plain string array (recommended): ["Option A", "Option B"]
An array of {label, value} objects (also accepted)

Endpoints

List forms

Method: GET
Path: /api/v1/{company}/forms
Scope: forms:read
Subscription: All plans, including Free

Path parameters

Name	Type	Description
`company`	string	Company sqid

Query parameters

Name	Type	Description
`q`	string	Filter by form name (substring match)
`page`	integer	Page number

Response `200`

{
  "data": [
    {
      "id": "v7KAa",
      "name": "Registration form",
      "created_at": "2026-02-01T10:00:00.4040+00:00",
      "fields": [
        {
          "id": "ff1Ab",
          "type": "text",
          "label": "Email address",
          "description": "We'll send your ticket here",
          "position": 0,
          "placeholder": "[email protected]",
          "required": true
        }
      ]
    }
  ],
  "links": { "...": "..." },
  "meta": { "...": "..." }
}

Use the form id (sqid) as form_id when attaching a form to a ticket type.

Form field fields

Field	Type	Description
`id`	string	Field sqid
`type`	string	Field type — see Form field types
`label`	string	Display label
`description`	string	Shown for types that allow descriptions
`options`	array	Options for choice fields
`position`	integer	Sort order
`placeholder`	string	Placeholder for supported types
`required`	boolean	Whether the field is required
`min`	number	Min value for number fields
`max`	number	Max value for number fields

Show form

Method: GET
Path: /api/v1/{company}/forms/{form}
Scope: forms:read
Subscription: All plans, including Free

Response `200`

Single FormResource with fields array.

Create form

Method: POST
Path: /api/v1/{company}/forms/create
Scope: forms:create
Subscription: All plans, including Free

Request body

See the request body table below for top-level field requirements. Individual form fields are validated when included in the fields array.

{
  "name": "Registration form",
  "fields": [
    {
      "type": "text",
      "label": "Email address",
      "description": "We'll send your ticket here",
      "placeholder": "[email protected]",
      "required": true,
      "position": 0
    },
    {
      "type": "company_name",
      "label": "Company",
      "position": 1
    }
  ]
}

Field	Required	Description
`name`	Yes	Form name
`fields`	Yes	Array of field objects
`fields[].type`	Yes	Field type — see Form field types
`fields[].label`	Yes	Display label
`fields[].description`	No	Field help text (not all types support it)
`fields[].placeholder`	No	Input placeholder
`fields[].required`	No	Mark field as required
`fields[].position`	No	Sort order (>= 0)
`fields[].options`	If type is `option` or `select`	String array or `{label, value}` objects — see Options format
`fields[].min`	No	Min for number fields
`fields[].max`	No	Max for number fields

Response `201`

Returns the created FormResource.

Update form

Method: PATCH
Path: /api/v1/{company}/forms/{form}
Scope: forms:update
Subscription: All plans, including Free

Request body

{
  "name": "Updated form name",
  "fields": [
    {
      "id": "ff1Ab",
      "label": "Updated label"
    },
    {
      "type": "text",
      "label": "New field",
      "position": 2
    }
  ]
}

Include id on a field to update an existing field.
Omit id to create a new field on the form.
Only name can be changed at the form level.

Response `200`

Returns the updated FormResource.

Not implemented

DELETE /api/v1/{company}/forms/{form} — no route exists (forms:delete scope is registered but unused). Forms created via the API cannot be deleted through the API.

Authentication
Conventions
Activations
Webhooks — submissions:subscribe scope

Start here

Reference

Endpoints

Forms

Forms

Overview

Form field types

Custom fields

Common fields

Field attributes by type

Options format

Endpoints

List forms

Path parameters

Query parameters

Response `200`

Form field fields

Show form

Response `200`

Create form

Request body

Response `201`

Update form

Request body

Response `200`

Not implemented

​Forms

​Overview

​Form field types

​Custom fields

​Common fields

​Field attributes by type

​Options format

​Endpoints

​List forms

​Path parameters

​Query parameters

​Response 200

​Form field fields

​Show form

​Response 200

​Create form

​Request body

​Response 201

​Update form

​Request body

​Response 200

​Not implemented

​Related

Forms

Overview

Form field types

Custom fields

Common fields

Field attributes by type

Options format

Endpoints

List forms

Path parameters

Query parameters

Response `200`

Form field fields

Show form

Response `200`

Create form

Request body

Response `201`

Update form

Request body

Response `200`

Not implemented

Related