# Forms

With the Forms module you build the forms on your own site (a contact form, a quote request in several steps, an intake form) in the dashboard, and the answers arrive in your [Inbox](/docs/forms/inbox). Your site loads the form from Borkol, so you can change questions, steps and texts without touching the site. Four more pages go deeper: [Build a form](/docs/forms/designer), [Show questions only for certain answers](/docs/forms/logic), [Inbox](/docs/forms/inbox) and [Spam protection and files](/docs/forms/spam-and-files).

Forms appears in the sidebar in the **Inbox** group when the module is enabled for the active business, with three items: **Inbox** (the submissions), **Forms** (the forms themselves) and **Settings** (the **Forms settings** that apply to every form, see [Spam protection and files](/docs/forms/spam-and-files#forms-settings)). Every member of the business sees the same screens and actions.

## Create a form

1. Open **Inbox** → **Forms** in the sidebar.
2. Click **New form**. The **New form** dialog opens.
3. Under **Start from**, pick a template. Each card shows its name, a short description and how many steps and fields it has:

   | Template | What you get |
   | --- | --- |
   | **Blank** | One empty step. Build the form yourself. |
   | **Contact** | Name, email, phone and a message, plus a consent checkbox. |
   | **Quote request** | Three steps: what, scope and budget, contact details. |
   | **Contractor quote** | Job type with follow-up questions, photos, address and contact details. |

4. Check the **Name** (filled in from the template) and the **Key**. The key fills itself in from the name until you change it: lowercase letters, digits and hyphens, starting with a letter. Your site loads the form by this key, and it is fixed once the form is published.
5. Click **Create form**. You land in the form editor on the **Build** tab.

Template texts come in your content languages where the template has a translation, otherwise in English, so check them before you publish.

## The forms list

**Inbox** → **Forms** lists your forms:

| Column | Description |
| --- | --- |
| Name | The form name. |
| Status | **Draft**, **Active** or **Archived** (see below). |
| Version | The published version, for example `v3`, or `—` when the form has never been published. A dot with **Unpublished changes** means you saved changes that are not live yet. |
| Submissions | How many submissions the form has received. |
| Updated | When the form was last changed. |

Click a row (or the eye icon) to open the form editor.

## Save, publish and activate

The editor's top bar shows the form's status, its published version (or **Not published**) and **Unpublished changes** when the saved draft differs from what your site gets. Next to it are **Preview**, **Save**, **Publish** and **Activate** or **Archive**.

- **Save** keeps your changes as a draft. Nothing changes on your site. If something needs fixing, a banner lists the problems (for example "Step 2: Your details"); click one to jump to it. Leaving the editor with unsaved changes asks **Leave the form editor?** first.
- **Publish** saves and then freezes the draft as a new version: "Published as version 3." Your site gets the new version from then on. Publish is only possible when there is something new to publish.
- **Activate** makes the form live: "Form is active. Sites can load it now." A form must be published once before you can activate it ("Publish the form before activating it.").
- **Archive** takes the form off your site after you confirm **Archive this form?**: sites can no longer load or submit it. Submissions you already received stay in your inbox, and you can activate the form again later.

A site only gets a form that is **Active** and published. A new form starts as **Draft**; publishing does not activate it, so do both before you add it to your site.

### Versions

Each publish creates a numbered version, and published versions are never changed again. Every submission remembers the version it was sent with, so when you reword a question, remove an option or delete a step later, older submissions in your inbox still show the questions and option labels the visitor actually answered. The form's name and the settings below are not versioned: they apply as soon as you save them.

## Preview

**Preview** opens your current version, unsaved changes included, in a side panel. Step through it with **Next**, **Back** and **Send**, and try the rules: questions appear and disappear as you answer. With more than one content language, switch languages with the tabs at the top. **Start again** resets it. Nothing is sent or stored ("Preview only: nothing was sent or stored."): a **File upload** question lets you pick files, but they are not uploaded anywhere.

## Settings tab

The **Settings** tab holds everything about the form except its questions. Texts are per language when your business has more than one content language; the default language needs a text. Save with **Save** in the top bar.

### General

- **Form name**: shown in your inbox and in the confirmation email as `{form}`.
- **Form key**: how your site loads the form. Lowercase letters, digits and hyphens, at most 64. The key is fixed once the form is published, because sites use it.

### Notifications

- **Send new submissions to**: up to ten email addresses that get an email for every new submission. Type an address and click **Add**. Leave the list empty to use the **Default recipients** from **Forms settings**, or, when there are none, your business email address.
- **Send from**: the email account that sends the notification and the visitor confirmation. **Use Forms default** sends with the account chosen for Forms mail under **Settings** → **Email** (see [Email accounts](/docs/workspace/email)). **Manage mail accounts** opens that section (`/settings/email`).

The notification email lists the visitor's name, email and phone, every answered question, and a link to the inbox. Replying to it replies to the visitor.

### Confirmation email

Switch on **Email the visitor a confirmation** to send the visitor an email after they submit. It goes to the answer of the first **Email** question in the form, in the visitor's language. Without an **Email** question the switch shows "This form has no Email question yet, so no confirmation can be sent."

Write a **Subject** and a **Message** for each language. Click a placeholder to insert it at the cursor:

| Placeholder | Becomes |
| --- | --- |
| `{name}` | The visitor's name (the answer to the question with key `name`). |
| `{form}` | The form name. |
| `{number}` | The submission number, for example `INQ-0042`. |
| `{answers}` | All visible questions and answers, one per line. Hidden fields are left out. |

### After sending

Choose what the visitor sees after a successful submission:

- **Show a thank-you message**: the visitor stays on the page and sees your **Thank-you message**.
- **Go to a page on your site**: the visitor is sent to the **Page URL** you enter, a thank-you page you host. It must be a full `https://` address.

### Spam protection

- **Cloudflare Turnstile**: visitors pass an invisible check before sending. It needs your Turnstile keys in **Forms settings** (the link next to the switch). When the switch is on but the keys are missing, a warning says "Turnstile is on, but your Forms settings have no site key and secret yet. Until both are set, sites show no check and submissions are not verified." with **Add your keys**.
- **Submissions per visitor** limits how often one visitor can send this form: between 1 and 100 per hour (5 by default). Extra attempts from the same visitor are refused, including attempts with mistakes in them.

See [Spam protection and files](/docs/forms/spam-and-files) for how these work together.

## Use on your site

The **Use on your site** tab has everything a developer needs to connect the form:

- **Form key** with a **Copy** button, and whether the form is live: "Live: sites get version 3 of this form.", or what is still missing (publish, activate).
- **Keep forms:write keys on your server**: an API key with `forms:write` can send submissions in your name, so it must never be in browser code. **Manage API keys** opens **Settings** → **API Keys** (see [API keys](/docs/workspace/api-keys)). Your site needs one key with both `forms:read` (to load forms) and `forms:write` (to send submissions); a separate read-only key is optional.
- **Load the form** and **Send a submission**: the two API calls with example responses. A form with a **File upload** question also shows **Upload a file**, the call that stores a file before the submission. With **Cloudflare Turnstile** on, **Send a submission** reminds your developer to show the Turnstile widget and reset it after every error.
- **With React**: how to install `@borkol/forms` and a ready-made form component, page and server route to copy.
- **Forms API reference**: a link to the [Forms API reference](/api/forms/index).