Reference → Forms — Reference

Forms — Reference

The Forms surface is the lead-capture engine — every contact form, signup form, gated download, quote request, and custom data-collection form on a site. It owns the form definition (fields, validation, layout), the submission store, third-party integration routing (CRM, email service provider, webhook target), reporting, and the import / export bundle.

This page is a reference for platform engineers and integrators. Customer-facing walkthroughs for building and routing forms live in the customer docs set; this page describes the surface, not the workflow.

Overview

Forms live under the Forms module in SG-Admin. The module renders five primary views — the form list, the form builder (create / edit), the submissions browser, the reports view, and the integrations panel — and exposes a write surface for form CRUD, duplicate, soft delete, restore, submission export, test dispatch, and bundle import / export.

A form is two things stored together: a schema (the field list, validation rules, layout) and a routing configuration (where submissions go — stored, emailed, forwarded to CRM, posted to a webhook, or all of these). The two are edited in the same builder UI but live as distinct shapes on the record.

Where it lives in SG-Admin:

Sidebar: SG-Admin → Forms
URL prefix: /sg-admin/forms/
View templates: application/views/Admin/Forms/

Submissions are kept indefinitely by default and live in the submissions store, queryable from the submissions view. The store is the source of truth — integration delivery is best-effort; if a CRM is down when a submission arrives, the submission is still recorded and retried.

┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Forms [+ New form] │├──────────────────────────────────────────────────────────────────────┤│ Name Fields Submissions Integrations Updated ││ ──────────────── ─────── ───────────── ────────────── ──────────││ Contact (Home) 7 428 Email + CRM 2d ago ││ Newsletter signup 2 1,204 ESP 1d ago ││ Quote request 11 67 Email + CRM 5d ago ││ Pricing inquiry 5 312 Webhook 8d ago ││ Old launch form 6 18 — trash ││ ││ [⋯ Edit] [⋯ Submissions] [⋯ Reports] [⋯ Duplicate] [⋯ Delete] │└──────────────────────────────────────────────────────────────────────┘

Actions

The Forms surface exposes the following operations.

List and search

Returns the form records, paginated, with name, field count, submission count, integration count, and updated-at columns. Supports column sort, free-text filter by name, and status filter (active / trashed).

Create form

Opens the form builder, empty. The builder offers a field palette (text, email, phone, textarea, select, multi-select, checkbox, radio, date, file upload, hidden, consent, captcha, custom-field reference) and a canvas where fields are arranged and configured. Each field carries a label, validation rules, default value, conditional-visibility logic, and placement metadata.

On submit, the schema persists, the routing configuration defaults to "store only" (no integrations), and the form is available for embed via shortcode or direct URL.

Edit form

Loads an existing form into the builder. Submit replaces the stored schema and routing configuration. Changes to the schema do not retro-apply to existing submissions — historical submissions carry the schema shape that was active when they arrived.

Duplicate

Creates a new form with the same schema and routing configuration, a copy-suffix in the name, and a fresh shortcode token. Submissions and reports do not copy.

Soft delete

Marks the form as trashed. Trashed forms stop accepting submissions (embedded instances on the public site return a "form unavailable" message) but the historical submissions remain queryable.

Restore

Returns a trashed form to active. Embedded instances resume accepting submissions.

Browse submissions

Returns the submissions for a form, paginated, with submission date, source URL, IP, and the field values as columns. Supports column sort, free-text search across field values, date-range filter, and integration-delivery-status filter (delivered / pending / failed). Each row opens a detail view with the full submission, the delivery log, and a manual-retry control.

Export submissions

Produces a CSV of submissions for a form. Supports selection-scoped (selected rows in the browser) or full-form export. The CSV column order matches the field order in the schema at export time.

Test dispatch

Sends a synthetic submission through the routing configuration without writing to the submissions store. Used to verify integration credentials, webhook payload shape, and email routing before going live. Returns a per-integration delivery report.

Submission reports

Returns aggregated metrics over a form's submissions: submissions per day (time-series), submissions by source page, conversion funnel (if a thank-you page is configured), and integration delivery success rate.

Manage integrations

Lists the integrations attached to a form (or to the site globally as defaults). Each integration is a typed record — email recipient, CRM connector, email-service-provider connector, generic webhook target, custom destination. Create, edit, toggle (active / paused), reorder (delivery order matters when one integration's response feeds another's payload), duplicate, and delete operations are available. Test connection verifies credentials without sending a submission.

Import forms

Bulk-loads forms from an exported bundle. Accepts the bundle, validates name and shortcode-token collisions (rename or skip), and reports per-form success or skip. Integrations are imported in paused state — credentials never travel in a bundle.

Export forms

Produces a bundle of form records (schema and routing configuration, without credentials). Selection-scoped or full-set.

Data model

A form record carries the following fields.

Field	Type	Notes
`id`	integer	Primary key.
`name`	string	Display name. Unique within the active set.
`shortcode_token`	string	Stable identifier used in the embed shortcode `{{form:}}`.
`schema`	JSON	Field list, validation rules, layout, conditional logic.
`routing_config`	JSON	Reference to integration records, delivery order, retry policy.
`status`	enum	`active` or `trash`.
`submit_button_label`	string	Customizable. Defaults to "Submit".
`success_action`	enum	`inline_message`, `redirect_url`, or `js_callback`.
`success_payload`	string	The inline message text, or the redirect URL, depending on `success_action`.
`consent_required`	boolean	When true, a consent checkbox is enforced in the schema.
`captcha_mode`	enum	`none`, `invisible`, `challenge`.
`created_at`	timestamp	Immutable.
`updated_at`	timestamp	Touched on save.

A submission record carries:

Field	Type	Notes
`id`	integer	Primary key.
`form_id`	integer	Foreign key to the form.
`field_values`	JSON	Map of field slug → submitted value.
`schema_snapshot`	JSON	The form's schema at submit time. Carried so historical submissions render correctly even after schema changes.
`source_url`	string	The page the form was submitted from.
`source_ip`	string	Submitter IP.
`user_agent`	string	Submitter user agent.
`delivery_log`	JSON	Array of integration delivery attempts (integration id, status, timestamp, response).
`submitted_at`	timestamp	Submit time.

File-upload fields. When a form schema includes a file-upload field, the submitted file commits to the Media library and the submission record carries the media id, not the binary.

Custom-field references. A form schema can reference custom fields defined in the Custom Fields module. Referenced fields render with their custom field configuration (label, type, validation) and submit through the same path as native fields.

Schema snapshot. Critical for historical accuracy — when an operator removes a field from a form's schema, the existing submissions still display the old value. The submission browser uses the snapshot for rendering, not the live schema.

PUBLIC-SITE SUBMIT│▼┌──────────────────────────┐│ Validation │ client + server, schema-driven└──────────────┬───────────┘│ valid▼┌──────────────────────────┐│ Persist submission │ → submissions store (always)│ + schema snapshot │└──────────────┬───────────┘│▼┌──────────────────────────┐│ Routing │ integrations dispatched in order│ ├─ Email recipient │ each writes to delivery_log│ ├─ CRM connector │ retry on failure (best-effort)│ ├─ ESP connector ││ └─ Webhook target │└──────────────┬───────────┘│▼Success action├─ inline_message├─ redirect_url└─ js_callback

Permissions

Access follows the standard admin gate plus per-action capability checks.

Capability	Administrator	Editor	Author	Viewer
List forms	✔	✔	✔	✔
Create form	✔	✔	—	—
Edit form	✔	✔	—	—
Duplicate	✔	✔	—	—
Soft delete	✔	✔	—	—
Restore	✔	✔	—	—
Browse submissions	✔	✔	✔	—
Export submissions	✔	✔	—	—
Test dispatch	✔	✔	—	—
View reports	✔	✔	✔	—
Manage integrations	✔	—	—	—
Import forms	✔	—	—	—
Export forms	✔	—	—	—

Submission privacy. Custom roles may scope submission visibility — for example, "sales role sees Quote-Request submissions only". The scope is configured under Settings → Roles and enforces at submission-browse time.

Audit. Every form save, duplicate, delete, restore, integration change, test dispatch, import, and export emits an Activity Log entry. Submission writes themselves are not logged (volume would swamp the log) — the submissions store is its own audit surface.

Sensitive-data handling. Forms that collect sensitive fields (credit card, government ID, health information) should not store the raw value in the submissions store. The schema supports per-field "do not store" flags — the field passes through to integrations but the submission record only carries a redacted placeholder.

SUBMISSION ARRIVES│▼integration order: [Email] → [CRM] → [Webhook]│├─► Email recipient delivered ✔ → delivery_log entry│├─► CRM connector failed ✗ → delivery_log + retry queue│ ││ ▼│ exponential backoff (1m, 5m, 30m, 2h, 12h)│ ││ ▼│ retry succeeds delivered ✔ → delivery_log update│└─► Webhook target delivered ✔ → delivery_log entrySubmissions store keeps the record regardless of delivery outcome.Manual retry available from the submission detail view.

Related references

Settings — Reference. Default consent text, captcha credentials, default integration list, submissions retention cap live in Settings.
Custom Fields — Reference. Form fields can reference shared custom-field definitions.
Media — Reference. File-upload submissions commit to the Media library.
Form Integrations — Reference. Connector types, credential storage, and the test-connection contract live in the dedicated Integrations reference.
Users — Reference. Per-role capability checks resolve against Users; submission privacy scope binds to role.
SEO — Reference. Success-action redirects and thank-you pages feed conversion tracking configured under SEO.

For the corresponding customer-facing walkthrough — building a form, routing to a CRM, exporting submissions — see the Forms section of the customer docs at /docs/forms.

On this page

Guides

Reference

Changelog

Roadmap