# Forms

Forms collect answers through public hosted pages. A form belongs to a workspace and stores each answer internally as a form submission record. Forms can email answers to a workspace or custom address, or trigger an active pipeline. A separate success action shows a message or redirects the visitor.

## Creating a form

1. Open **Forms** from the workspace navigation.
2. Click **New Form**.
3. Add the questions the hosted page should collect.
4. In **Settings**, choose a **Submit action**. For a pipeline, select an active pipeline and map questions to its expected fields.
5. Choose a **Success action**: show a message or redirect to an HTTPS URL.
6. Publish the form when it is ready to share.

Draft forms are not available through public hosted URLs.

## Fields

Forms define their own hosted questions. Every answerable question has a **Label**, **Name**, and **Type**. The builder shows only settings that apply to that type, such as a placeholder, helper text, default value, required state, options, or validation limits. Heading and paragraph blocks structure the page without collecting an answer. All blocks can be reordered at any time.

**Name** is the question's stable identifier. It is stored as `key` in the form definition and is used when an answer is validated or passed to a pipeline.

Answers are validated against the published form definition, then stored with the form.

Use this for intake flows such as leads, feedback, applications, or editorial intake.

## Submit action

Choose what happens to each accepted answer:

- **Save answer only** — store the answer without sending email or running a pipeline. Existing standalone forms keep this behavior.
- **Send to workspace email** — email the answer to the current address in **Settings → General → Workspace Email**. An info alert shows the destination.
- **Send to custom email** — enter one valid **Recipient email** for this form. The recipient does not need a workspace account.
- **Trigger pipeline** — select an active pipeline and map its input fields.

Answers are always stored on the form. Email notifications contain question labels and validated answers. Invalid submissions do not send email, and retries with the same submission token do not send duplicate notifications. Recipients are not exposed on the public form. Form emails are independent of workspace and personal notification toggles. Notifications use the configured mail transport and queue; a worker must be running for an asynchronous queue. A `log` mailer records messages without sending them. See [Email Settings](/docs/platform/email-settings#delivery-and-queues) for delivery troubleshooting.

## Success action

Choose what the visitor sees after submission:

- **Show Success Message** — display the form's success message.
- **Redirect to URL** — send the visitor to an HTTPS URL.

Both options work with every submit action. Queued pipelines show a processing message first; redirects happen only after the pipeline succeeds. A failed pipeline shows an error instead of the success message or redirect, including when it runs synchronously. Form-level validation errors appear above the questions and keep the entered answers. Email delivery runs independently of the visitor's success response.

When a pipeline is triggered, validated answer values are passed under `input.fields`, the form ID is available as `input.form_id`, and the answer ID is available as `input.answer_id`. The previous `input.submission_id` key remains as a compatibility alias. Mapped field values are available as top-level pipeline input keys where applicable.

Use the email submit actions for a copy of each answer. Use a pipeline for custom email content, external requests, entry creation, or multiple steps.

## Field types

Forms support text, textarea, rich text, email, URL, phone, slug, path, number, select, multi-select, checkbox, radio, date, date/time, time, and hidden fields. Public form file-upload questions are not supported. The [Files API](/docs/api/files) accepts authenticated uploads for workspace integrations.

New choice options are stored as plain strings, with one option per row in the builder; legacy label/value pairs remain intact until their options are edited. Text questions can set minimum and maximum lengths. Number questions can set minimum, maximum, and step values, with step increments measured from the minimum, default, or zero. Questions can also define an optional pipeline target mapping.

## Conditions

Each question has one simple conditional behavior:

- **Always show** — do not apply a condition.
- **Show when** — show the question only when another answer matches.
- **Hide when** — hide the question when another answer matches.
- **Required when** — require the question when another answer matches.

Choose another question and one of four operators: **Is answered**, **Is empty**, **Is**, or **Is not**. The last two also require a comparison value.

For example, this condition shows a question when `account_type` is `Business`:

```json
{
  "ignore_unless": {
    "field": "account_type",
    "operator": "equals",
    "value": "Business"
  }
}
```

Stored conditions use `required_if`, `hidden_if`, or `ignore_unless`, with `filled`, `empty`, `equals`, or `not_equals` operators. Existing `ignore_if` conditions remain supported for compatibility and appear as **Hide when** in the builder.

## Hosted URLs

Published forms have public URLs in this format:

```http
GET /@{workspace}/forms/{form}
POST /@{workspace}/forms/{form}/submit
```

Hosted forms use workspace branding from hosted authentication settings and are rate limited. Public pages expose only the form definition needed to render and submit the form.

For clients requesting JSON, a completed submission returns `200`, a queued pipeline returns `202` with a signed `status_url`, and a synchronous pipeline failure returns `422` with `status: "failed"`. Failed pipelines never include a redirect destination. Retain the same submission token when retrying a request to avoid repeating its side effects.

## Related pages

- [Email Settings](/docs/platform/email-settings) — Form recipients, mail transport, and queues.
- [Pipelines](/docs/platform/pipelines) — Build workflows that forms can trigger after receiving an answer.
- [Entries](/docs/content/entries) — Manage content created by pipelines or API entry actions.