> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webstorio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms SDK

> window.webstorio form methods — load schemas, submit responses, and list public submissions.

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.

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

Returns:

```javascript theme={"dark"}
{
  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 `id`s from the schema.

```javascript theme={"dark"}
const result = await window.webstorio.submitForm("contact", {
  "field-name-id": "Ada Lovelace",
  "field-email-id": "ada@example.com",
  "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`.

```javascript theme={"dark"}
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.

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

## Example — load and submit

```javascript theme={"dark"}
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](/guides/forms)