---
name: basestack-forms
description: Integrate Basestack Forms using HTML, fetch, React/Next.js, or Vue; choose redirects or JSON responses, validate fields and attachments, handle recoverable UI states, and configure verified webhook/email delivery without inventing an SDK or native connector.
---

# Basestack Forms

Last reviewed: 2026-10-16. Contract baseline: Forms API `/v1` submission route
and delivery workers in the repository on this date. There is no dedicated
Forms SDK in this integration inventory. Check the deployed API/self-hosted
release when behavior differs; public docs do not grant account access.

## When to use

Use for contact forms, lead capture, feedback, or other authorized submissions
from an existing application. Standard HTML or HTTP is sufficient; MCP is not
required and does not replace frontend integration knowledge.

## Required inputs

- Stack/runtime and whether to redirect the browser or remain on the page.
- The real form endpoint/key copied from the dashboard, and the test environment.
- Field names, configured validation rules, honeypot name, and enabled state.
- Redirect URLs, retention, uploads, website/IP restrictions, and delivery needs.
- Consent for personal data collection and any forwarding/notification destination.

If missing, explain [form creation](https://docs.basestack.co/content/forms/user-guide/forms)
and [endpoint setup](https://docs.basestack.co/content/forms/user-guide/setup).
Never fabricate a key or create/change account resources without approval.

## Choose an integration

- Browser navigation, no JavaScript: [HTML](references/html.md).
- JSON/fetch, a server client, or files: [JavaScript/REST](references/javascript-rest.md).
- Interactive React or Next.js: [React/Next.js](references/react-nextjs.md),
  plus [JavaScript/REST](references/javascript-rest.md) for the response contract.
- Vue: [Vue](references/vue.md).
- Rules, honeypot, privacy, retention, attachments:
  [validation, security, and files](references/validation-security-files.md).
- Webhook POST and configured email notifications:
  [integrations](references/integrations.md).

## Workflow

1. Inspect existing form/state/validation patterns and confirm the real endpoint.
2. Choose `POST https://forms-api.basestack.co/v1/s/FORM_KEY` for HTML redirects
   or append `?mode=rest` for JSON response mode. `Accept` alone does not select
   JSON mode. Replace the named `FORM_KEY` placeholder before use.
3. Use ordinary HTML/HTTP; do not install an invented `@basestack/forms-react`
   or other unpublished Forms SDK. Use JSON, URL-encoded data, or multipart.
4. Give fields accessible labels and `name` attributes matching server rules.
   Use a real configured honeypot name, not an assumed magic `_trap` field.
5. Provide pending/success/error states, prevent accidental duplicate clicks,
   inspect HTTP status and JSON body, and preserve inputs after failure.
6. For files, enable retention and uploads, use `FormData`, and let the browser
   set the multipart boundary. Current limits: 1 MiB per file, five files total.
7. Review security/privacy and webhook/email settings. Acceptance is not delivery.
8. Add mocked tests. Send a synthetic test to a non-production form only with
   permission, especially if notifications or forwarding will be triggered.

## Verification

Cover success, invalid fields/rules, disabled form, wrong key, honeypot rejection,
network failure, malformed/non-JSON error responses, duplicate-click prevention,
and file count/size failures. Verify dashboard retention and receiver/email
delivery separately after an approved test. Do not report a hypothetical live
test as passed or automatically retry an ambiguous submission.

## Safety constraints

- The submission endpoint is browser-visible, not a private account credential.
  Keep private API/MCP tokens, webhook destination credentials, and email service
  secrets out of frontend code and public Markdown.
- Client validation, CORS, website restrictions, and a honeypot do not prevent
  all abuse or prove identity. Validate fields on the server using configured rules.
- Non-string JSON fields are stringified; do not promise nested typed storage.
- Native delivery covered here is webhook POST and email notifications only.
  Google Sheets and native Slack/Discord connectors are unverified/unreleased
  for this guide. Do not invent setup or blindly forward to incompatible APIs.
- Webhooks are asynchronous and can retry/duplicate. The current sender has no
  signature header or stable event ID; do not invent HMAC or exactly-once delivery.
- Obtain consent before forwarding personal data to a new destination or sending
  tests that trigger email/webhooks. Avoid real personal data in fixtures/logs.
- Query-string submission data can leak into history, logs, analytics, or referrers.
  Keep it disabled for sensitive forms; retention-off does not disable forwarding.

Human setup: [Using these files with an AI assistant](https://docs.basestack.co/content/forms/guides/ai-agents).