<!-- Canonical URL: https://www.usebluehill.com/features/forms -->
<!-- Source: https://www.usebluehill.com/features/forms.md -->

# Forms — intake, onboarding, and feedback collection

> BlueHill's form builder captures structured data from customers and contacts. Forms attach to onboarding tasks, submit through the customer portal, and feed directly into the customer record.

## What BlueHill forms do

Forms in BlueHill aren't a separate survey product bolted on the side — they're a first-class data-capture layer wired into the customer record and onboarding workflow. Every form belongs to your tenant, every submission attaches to a customer (or creates one), and submissions can auto-progress tasks.

The three places forms earn their keep:

1. **Onboarding intake** — capture brand assets, IdP metadata, billing details, integration credentials. Linked to an onboarding task that completes when the form does.
2. **Support intake** — ticket creation forms with structured fields (severity, category, environment) that pre-populate the ticket on submission.
3. **Feedback collection** — NPS, CSAT, post-engagement surveys. Multi-submission, time-bound, scoring fields.

## The data model

Each `Form` carries:

- **`name`** — internal label
- **`description`** — what it's for
- **`form_structure`** — the JSON definition of fields, validation, conditional logic
- **`allow_multiple_submissions`** — whether one contact can submit multiple times
- **`linked_to`** — optional task or workflow this form belongs to

Each `FormSubmission` carries:

- **Submitter contact** — auto-linked to a customer (by email domain) or stored as a standalone contact
- **Customer ID** — the customer record this submission attaches to
- **Submitted timestamp**
- **Field values** — the structured response
- **Files** — any uploads in the submission
- **Linked task** — if the form was on a CustomerTask, this is the task that auto-progresses

## Supported field types

The `form_structure` JSON supports:

- **Text** — single-line input
- **Long text** — multi-line textarea
- **Number** — numeric with optional min/max
- **Email** — validated email format
- **URL** — validated URL
- **Date** — date picker
- **Single-select** — dropdown
- **Multi-select** — checkboxes
- **Checkbox** — yes/no
- **File upload** — single file, MIME-type filtered
- **Signature** — drawn signature, stored as image
- **Conditional fields** — show/hide based on another field's value

The structure is stored as JSON which means new field types can be added without database migrations.

## Linking forms to onboarding tasks

The killer pattern is forms attached to `CustomerTask`. The CustomerTask carries `form_id` and `form_name` fields, which create the link. When a customer-facing task is "Submit brand assets" and you've linked a form, the customer sees:

1. The task in their portal
2. A "Complete form" button
3. The form inline (no separate page navigation)

When they submit, the form data lands on the customer record, the task auto-progresses to Done, and the next task in the onboarding template kicks off.

This eliminates the dance of "I emailed you the questions, you emailed back, I copy-pasted into our system" that most teams burn 20-30% of onboarding cycle time on.

## Forms in the portal

The [customer portal](/features/customer-portal) is the natural surface for forms. Customers see:

- Forms assigned to them via tasks
- Forms attached to their account (e.g. annual NPS survey)
- Their submission history

Each form takes the portal's branding (your logo, your colors, your subdomain). The customer never knows they're using BlueHill — they're using your product.

## Embedding forms outside the portal

For pre-sale or pre-portal use cases (gated content downloads, intake from your marketing site), every form has:

1. **Public link** — shareable URL anyone can visit
2. **Embed snippet** — `<iframe>` for putting on your marketing site
3. **JavaScript embed** — for inline rendering with your own styling

Submissions still attach to customer records: if the email-domain matches an existing customer, it links there. If not, a new contact record is created (which you can later promote to a customer).

## File uploads

File fields accept uploads in common formats (PDF, DOC, XLSX, images). Files are stored encrypted at rest, with download URLs scoped to authenticated sessions.

The customer's uploaded files surface in three places:
1. The original FormSubmission record
2. The linked task (if any)
3. The customer's document store

## What this replaces

Teams arriving at BlueHill for the form feature usually replace:
- Typeform / Jotform for intake (separate product, no link to customer record)
- Google Forms (no auth, no link to customer record)
- Email-only data collection (unstructured, hard to query)

## Built for

- [SaaS implementation teams](/use-cases/saas) capturing structured data at onboarding kickoff
- [Customer success teams](/use-cases/customer-success) running NPS/CSAT surveys
- [Agencies](/use-cases/agencies) collecting brand assets and intake info per client

## Try it

[Start a 14-day free trial](https://app.usebluehill.com/sign-up) — no credit card required.