# Heapform

> Form backend for HTML and JavaScript forms. POST to a Heapform endpoint. Heapform stores submissions, sends email, validates fields, and can forward data to webhooks.

## Endpoint

Production: `https://forms.heapform.com/f/YOUR_FORM_SLUG`
Development: `https://forms-dev.heapform.com/f/YOUR_FORM_SLUG`

Replace `YOUR_FORM_SLUG` with the slug from the dashboard.

POST content types:
- `application/x-www-form-urlencoded` for HTML forms
- `multipart/form-data` for HTML forms with files
- `application/json` for fetch and JS apps

Success (JSON): `{ "success": true, "returnUrl": "https://..." | null }`
Validation error (422): `{ "success": false, "code": 422, "errors": { "field": { "message": "...", "rule": "required" } } }`

HTML forms redirect to `returnUrl` when set (Starter+).

## Get started

1. Sign up: https://heapform.com/app/auth/register
2. Create a workspace: https://heapform.com/app/auth/create-workspace
3. Create a form in the dashboard
4. Copy the endpoint URL (example: `https://forms.heapform.com/f/abc123`)
5. Set your form `action` or `fetch` URL to that endpoint
6. Submit a test and check **Submissions** in the dashboard

After the form exists, ask the user to paste the endpoint URL back into the chat.

## Examples

### HTML

```html
<form action="https://forms.heapform.com/f/YOUR_FORM_SLUG" method="POST">
  <input type="text" name="name">
  <input type="email" name="email">
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>
```

### JavaScript

Use `@heapform/react` for React and Next.js apps, or `fetch` for plain JavaScript.

```javascript
const response = await fetch("https://forms.heapform.com/f/YOUR_FORM_SLUG", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Jane", email: "jane@example.com", message: "Hi" }),
});

const data = await response.json();
```

### File uploads

Starter plan or above.

```html
<form action="https://forms.heapform.com/f/YOUR_FORM_SLUG" method="POST" enctype="multipart/form-data">
  <input type="email" name="email">
  <input type="file" name="documents" multiple>
  <button type="submit">Upload</button>
</form>
```

Files are served from `https://assets.heapform.com/{formSlug}/uploads/...`.

### cURL

```bash
curl -X POST "https://forms.heapform.com/f/YOUR_FORM_SLUG" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane","email":"jane@example.com","message":"Hi"}'
```

## Validation

Set rules in the dashboard under **Validation**.

Rules: `required`, `phoneNumber`, `number`, `url`, `minLength`, `maxLength`, `contains`, `notContains`

Only use `required` when the field is needed to handle the submission. Message fields can stay optional.

422 example:

```json
{
  "success": false,
  "code": 422,
  "errors": {
    "email": { "message": "The email field is required.", "rule": "required" }
  }
}
```

## Spam protection

Enabled by default per form. Flagged submissions are still saved, marked as spam in the dashboard, never sent to webhooks, and do not count toward the monthly quota. Email notifications for spam are opt-in. The submitter always gets a normal success response.

Add a hidden honeypot field. Bots fill it in, people don't:

```html
<input type="text" name="_gotcha" tabindex="-1" autocomplete="off" style="display:none" />
```

Other signals: link markup (`<a href>`, `[url]`), many links, links in name fields, URL shorteners, executable attachments (`.exe`, `.html`...), random strings, spam keywords, scripted clients, bursts from the same IP, links to a page made for the site (such as `example.online/b2b/your-brand`), links and emails on throwaway domains (`.online`, `.xyz`, `.top`...), and generated sender addresses (`firstname.lastname1234@`).

For stronger protection, enable a CAPTCHA (Cloudflare Turnstile, Google reCAPTCHA, hCaptcha) in form settings.

## Webhooks

Pro and Business only. Set up to 5 webhook URLs in form settings.

Event: `form.submission.created`

Headers:
- `Content-Type: application/json`
- `User-Agent: Heapform Webhook/1.0`
- `X-Heapform-Event: form.submission.created`
- `X-Heapform-Delivery-Id: {submission-id}`

Payload:

```json
{
  "id": "submission-id",
  "type": "form.submission.created",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "data": {
    "submission": {
      "id": "submission-id",
      "formSlug": "form-slug",
      "fields": [{ "name": "email", "value": "jane@example.com" }],
      "attachments": [{ "field": "documents", "filename": "file.pdf", "url": "https://...", "type": "application/pdf", "size": 12345 }],
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "referer": "https://example.com",
      "countryCode": "US",
      "status": "SUCCESS",
      "isSpam": false,
      "createdAt": "2024-01-01T00:00:00.000Z"
    },
    "form": {
      "slug": "form-slug",
      "title": "Contact Form"
    }
  }
}
```

## Email notifications

Add recipients in form settings. Emails come from `Heapform <updates@notifications.heapform.com>`.

## Return URL

Starter+. Set in form settings. HTML forms redirect after submit. JSON responses include `returnUrl`.

## Plans

- Hobby ($0): 3 forms, 100 submissions/month, 1 members, 1 notification emails/form. Includes 30-day archive
- Starter ($90.00/year ($7.50/mo)): 10 forms, 500 submissions/month, 2 members, 2 notification emails/form, 5.0 MB/file, 5.0 MB/submission, 1.0 GB storage. Includes return URL, file uploads, 1 custom email domain, 1-year archive
- Pro ($20.00/mo or $200.00/year ($16.50/mo yearly)): 50 forms, 2,500 submissions/month, 5 members, 5 notification emails/form, 25 MB/file, 50 MB/submission, 5.0 GB storage. Includes return URL, webhooks, file uploads, 3 custom email domains, forever archive
- Business ($80.00/mo or $800.00/year ($66.50/mo yearly)): 250 forms, 10,000 submissions/month, 10 members, 10 notification emails/form, 25 MB/file, 100 MB/submission, 50 GB storage. Includes return URL, webhooks, file uploads, 10 custom email domains, forever archive

Quota resets on the workspace billing cycle day. Submissions stop at the monthly limit. Alerts at 75%, 90%, and 100%. Downgrading does not reset usage.

Pricing: https://heapform.com/pricing

## Templates

HTML templates at https://heapform.com/templates

Categories: contact, application, feedback, registration, request, signup

Steps: create a form, replace `YOUR_FORM_SLUG`, publish, test.

## Dashboard paths

- `https://heapform.com/app/{workspaceSlug}/forms/{formSlug}/submissions`
- `https://heapform.com/app/{workspaceSlug}/forms/{formSlug}/validation`
- `https://heapform.com/app/{workspaceSlug}/forms/{formSlug}/analytics`
- `https://heapform.com/app/{workspaceSlug}/forms/{formSlug}/settings`

## Export API

Requires login.

`GET /api/forms/{formSlug}/export?workspaceSlug={workspaceSlug}&format=csv`
`GET /api/forms/{formSlug}/export?workspaceSlug={workspaceSlug}&format=json`

## FAQ

### What is Heapform?

Heapform is a form backend for HTML and JavaScript forms. You point your form at a Heapform endpoint, and Heapform stores each submission, validates fields, filters spam, sends email notifications, and can forward data to your own webhooks. You keep full control of the form's markup and design.

### Do I need my own server to use Heapform?

No. Your form posts directly to an endpoint like https://forms.heapform.com/f/YOUR_FORM_SLUG, so it works on static sites and on hosts like Vercel, Netlify, Cloudflare Pages, and GitHub Pages without any backend code.

### Which frameworks does Heapform work with?

Any site that can send an HTTP POST. Plain HTML forms work with no JavaScript. Fetch-based forms can send JSON, and React and Next.js apps can use the @heapform/react SDK. Endpoints accept URL-encoded, multipart, and JSON bodies.

### Is Heapform free?

Yes. The Hobby plan is free and includes 3 forms and 100 submissions per month, with no credit card required. Paid plans add more forms and submissions, file uploads, team members, and webhooks.

### How does Heapform handle spam?

Spam protection is on by default for every form. Heapform checks a honeypot field and other signals such as link-heavy messages, scripted clients, and bursts from one IP address. You can also enable Cloudflare Turnstile, hCaptcha, or Google reCAPTCHA. Flagged submissions are kept and marked as spam, never sent to webhooks, and don't count toward your monthly quota.

### Can visitors upload files?

Yes, on the Starter plan and above. Use a multipart form with file inputs; uploads are stored for you and linked from each submission, up to 100 MB per submission on the largest plan.

### Can I send submissions to my own API, Slack, or CRM?

Yes, with webhooks on the Pro plan and above. Heapform sends a JSON payload for each new submission to up to 5 URLs per form. Spam is never forwarded. There are no built-in Slack or CRM integrations yet, so webhooks are the integration point.

### Does Heapform validate form fields?

Yes. Configure rules per field in the dashboard (required, number, URL, phone number, minimum and maximum length, contains, and does not contain). Invalid submissions get a 422 response with a structured error for each field, which you can show in your UI.

### Can I export my submissions?

Yes. Export any form's submissions as CSV or JSON from the dashboard. Submissions are kept according to each form's archive setting, from 30 days up to forever depending on your plan.

### Can an AI coding assistant set up Heapform for me?

Yes. Heapform publishes an llms.txt file with the endpoint format, request and response examples, validation rules, and webhook payloads, so assistants like Claude, Cursor, or Copilot can wire up a form correctly. You still create the form in the dashboard and paste its endpoint URL.

### Is there a free plan?

Yes. The Hobby plan is free and includes 3 forms and 100 submissions per month. No credit card is required to get started.

### Can I upgrade or downgrade my plan?

Yes. You can change plans anytime from your workspace billing settings. Upgrades take effect immediately. Downgrades apply at the end of your current billing period.

### What counts as a submission?

Every accepted form post to one of your endpoints counts as one submission. Submissions flagged as spam are still saved for review, but they don't count toward your monthly quota.

### What happens if I exceed my submission limit?

New submissions are blocked until your quota resets or you upgrade to a higher plan. We send email alerts at 75%, 90%, and 100% of your monthly limit.

### When does my submission quota reset?

Submission counts reset on your workspace billing cycle day each month, based on when your subscription started.

### Is the Starter plan available on monthly billing?

No. Starter is billed yearly only, at $90 per year. Pro and Business are available on both monthly and yearly billing.

### Is yearly billing cheaper?

Yes. Yearly billing saves about 18% on Pro ($16.50/mo instead of $20.00/mo) and a similar amount on Business.

### What happens when I cancel my subscription?

You keep access to your paid plan until the end of the current billing period. After that, your workspace is downgraded to the Hobby plan. Your submission usage carries over and does not reset on downgrade.

### Do you offer refunds?

Paid plans are billed in advance and fees are non-refundable unless otherwise stated in our Terms of Service. If something went wrong with your billing, contact us and we'll look into it.

### What payment methods do you accept?

We accept major credit and debit cards through Stripe. You can update your payment method anytime from the billing portal.

### I have a question about billing or need a custom plan.

Reach out through our contact page and we'll help you find the right setup.

## Links

- Contact: https://heapform.com/contact
- Pricing: https://heapform.com/pricing
- Templates: https://heapform.com/templates
- Guides: https://heapform.com/guides
- Alternatives: https://heapform.com/alternatives
- Privacy: https://heapform.com/privacy
- Terms: https://heapform.com/terms