Forms SDK

Form & Survey methods for published sites. Requires the Form & Survey feature (form_and_survey). Identify forms by their key (for example contact or newsletter) — the same key shown in the dashboard.

getFormSchema(formKey) / getForm(formKey)

Load the form name, field schema, and settings. getFormSchema and getForm are aliases.

const { name, schema, settings } = await window.webstorio.getFormSchema(
  "contact",
);

Returns:

{
  name: "Contact",
  schema: [
    {
      id: "field-uuid",
      type: "email",       // see field types below
      label: "Email",
      required: true,
      validation: { /* optional */ },
    },
    // ...
  ],
  settings: {
    uniqueFieldId: null,           // field id that must be unique across submissions
    isClosed: false,
    maxSubmissions: null,          // number or null (unlimited)
    publicSubmissionsListing: false,
  },
}

Build the UI from schema. Field id values are the keys you pass to submitForm.

Field types

Type	Typical value
`text`	string
`longtext`	string
`number`	number
`boolean`	boolean
`date`	string (date)
`time`	string (time)
`url`	string
`email`	string
`select`	string (option value)
`multiselect`	string[]
`checkbox`	string[]
`radio`	string
`linear_scale`	number

validation may include minLength, maxLength, min, max, pattern, and options ({ value, label }[]) for select-style fields.

submitForm(formKey, data)

Submit a response. Keys in data must match field ids from the schema.

const result = await window.webstorio.submitForm("contact", {
  "field-name-id": "Ada Lovelace",
  "field-email-id": "[email protected]",
  "field-message-id": "Hello!",
});
// { id: "submission-uuid", submittedAt: "..." }

Rejects when the form is closed, over maxSubmissions, fails validation, or violates a unique-field constraint (HTTP 409).

getFormSubmissions(formKey, options?)

List submissions. Requires public submissions listing enabled on the form (settings.publicSubmissionsListing). Otherwise the API returns 403.

const { submissions, pagination } = await window.webstorio.getFormSubmissions(
  "contact",
  { limit: 20, offset: 0 },
);

// submissions: [{ id, dataJson, submittedAt }, ...]
// pagination: { limit, offset, total }

dataJson keys are field ids; values match the field types above.

getFormSubmissionById(formKey, submissionId)

Fetch one submission. Also requires public submissions listing.

const { submission } = await window.webstorio.getFormSubmissionById(
  "contact",
  submissionId,
);
// { id, dataJson, submittedAt }

Example — load and submit

const { schema, settings } = await window.webstorio.getFormSchema("contact");

if (settings.isClosed) {
  // show closed state
}

async function handleSubmit(values) {
  try {
    await window.webstorio.submitForm("contact", values);
    // success
  } catch (err) {
    // err.message — validation or server error
  }
}

User guide

Non-technical setup: Forms & surveys

Overview

CLI

Client SDK

MCP Server

Help

getFormSchema(formKey) / getForm(formKey)

Field types

submitForm(formKey, data)

getFormSubmissions(formKey, options?)

getFormSubmissionById(formKey, submissionId)

Example — load and submit

User guide

​getFormSchema(formKey) / getForm(formKey)

​Field types

​submitForm(formKey, data)

​getFormSubmissions(formKey, options?)

​getFormSubmissionById(formKey, submissionId)

​Example — load and submit

​User guide

getFormSchema(formKey) / getForm(formKey)

Field types

submitForm(formKey, data)

getFormSubmissions(formKey, options?)

getFormSubmissionById(formKey, submissionId)

Example — load and submit

User guide