Form Templates

A form template defines the structure, appearance and behaviour of the forms you send to contacts. It is what you design in Penbox Studio, the form builder.

For administrators and creators: this section is for the people who design form templates. If you only need to send forms to contacts, see Forms.

What a template defines

Structure — steps and the elements that collect data
Portal experience — the welcome, review and ending pages
Behaviour — conditional logic, variables, calculations and integrations
Notifications — invitations, reminders and completion emails
Automations — actions triggered by what happens to the form
Appearance — branding and layout

Elements

Every element type you can put in a form, and how to configure it

Steps and logic

Organise elements into steps and branch on answers

Portal pages

Welcome, review and ending screens

Versioning

Templates are versioned, so you can keep iterating on a design without disturbing the forms already in the wild.

Create a template — starts as version 1
Make changes — edit in draft
Publish the version — locks it for use
Create a new version — keep iterating
Publish when ready — new forms use the latest published version

Version properties

Version number — auto-incremented integer (1, 2, 3…)
Published — published versions can be used in form presets
Deprecated — marks an old version as no longer recommended
Active version — form presets follow the latest published version by default

A form always keeps the version it was created with. Publishing a new version never changes forms already in progress — only newly created forms pick it up.

Basic information

Field	Description	Required
Name	Template identifier (max 64 chars)	Yes
Slug	URL-friendly identifier	Auto-generated
Version	Version number	Auto
Locale	Default language (2-char code)	Yes
Description	What this template is for (max 1000 chars)	No

Multiple languages

A template supports several languages through its locales and strings configuration. Locales

["en", "fr", "es", "de"]

Strings

{
  "en": {
    "welcome_title": "Welcome",
    "submit_button": "Submit"
  },
  "fr": {
    "welcome_title": "Bienvenue",
    "submit_button": "Soumettre"
  }
}

Contacts can switch language in the portal, and every translated string follows.

Automations

Automations are actions triggered by what happens to a form. An automation has a name, an optional icon, an optional delay in minutes, the list of events it reacts to in on, and its actions.

Triggers

Event	Fires when
`responses:created`	A response is created, as a draft
`responses:updated`	A response is updated
`responses:completed`	The form is completed and submitted
`responses:declined`	The contact declines the form
`requests:active`	The form becomes active
`requests:expired`	The form expires without being completed
`manual`	A team member runs it by hand

Actions

Each action has a type and an options object, plus optional ref, name, if, as and result.

Type	Does
`email`	Sends an email
`data-push-email-v2`	Sends the collected data by email
`http`	Calls an external HTTP endpoint
`core`	Acts on Penbox data
`file`	Produces or transforms a file
`connection_fetch`	Reads from a connected system
`ai_generate_data`	Generates data with the assistant

{
  "automations": [
    {
      "id": "8b1c…",
      "name": "Notify the broker",
      "icon": "envelope",
      "delay": 0,
      "on": ["responses:completed"],
      "actions": [{ "type": "email", "options": { "…": "…" } }]
    }
  ]
}

Use delay to wait before running — 1440 for a reminder one day after the response was created.

Notifications

Notifications are emails about the form itself, sent to your team rather than driven by an automation.

{
  "notifications": [
    {
      "type": "email",
      "to": [{ "email": "admin@company.com" }, { "role": "owner" }],
      "on": ["responses:completed"]
    }
  ]
}

Each recipient is either an email or a role — owner or creator, never both at once. Notifications fire on responses:completed or on request_notifications:bounced, when an invitation email bounces. Emails sent to the contact — invitations, reminders, confirmations — are configured separately. See Notifications.

Publishing

Build and test the template
Check every step and element behaves as expected
Publish the version, which locks it
The version can now be used in form presets

Before publishing, make sure that:

Conditional logic behaves as expected
Required fields are the right ones
Images and assets load
Translations are complete, if the template is multilingual
Automations are correctly configured
A test submission works end to end

Best practices

Design mobile-first

Most contacts complete forms on a phone. Test on a small screen.

Keep forms short

Only ask for what you need. Every extra field costs completion rate.

Use steps deliberately

Break a long form into logical steps, but don’t overdo it — three to five steps is usually the sweet spot.

Write real help text

Use the help on a title to explain what you expect, especially on fields that are unusual or formatted.

Test before publishing

Always run the whole flow before publishing. Submit test data and check the automations actually ran.

Hide what doesn't apply

Conditional steps and elements keep the form short for each contact.

Always confirm

Send a confirmation on completion. It builds trust and acts as a receipt.

Version deliberately

Don’t cut a new version for a typo. Batch changes to avoid version sprawl.

Next steps

Form presets

Configure presets from a template

Notifications

Invitations, reminders and confirmations

Embedding

Show a form inside your own site

Forms

Understand form instances

Get Started

Workspace

Penbox Agent

Cases

Forms

Penscript

What a template defines

Elements

Steps and logic

Portal pages

Versioning

Version properties

Basic information

Multiple languages

Automations

Triggers

Actions

Notifications

Publishing

Best practices

Next steps

Form presets

Notifications

Embedding

Forms

​What a template defines

Elements

Steps and logic

Portal pages

​Versioning

​Version properties

​Basic information

​Multiple languages

​Automations

​Triggers

​Actions

​Notifications

​Publishing

​Best practices

​Next steps

Form presets

Notifications

Embedding

Forms

What a template defines

Versioning

Version properties

Basic information

Multiple languages

Automations

Triggers

Actions

Notifications

Publishing

Best practices

Next steps