Secure form intake for modern websites.

1. Step 1

   Create a Site using the website's canonical domain.

2. Step 2

   Create a Hook for the form or workflow.

3. Step 3

   Configure notification routing, allowed origins, and optional approved-webhook delivery.

4. Step 4

   Build the visible form in the website or install a maintained adapter.

5. Step 5

   Submit the browser form to a same-origin site handler.

6. Step 6

   Validate the request and verify Turnstile or captcha before forwarding.

7. Step 7

   Forward the request to the Hook with the intake secret on the trusted server.

8. Step 8

   Run a safe test and verify Inbox, Activity, files, and expected delivery behavior.

• Public signup is closed. Ask the operator to create your human login and a separate agency workspace with you as Owner.
• A new agency must not be added as a team member of another agency. The create_user API creates membership inside the calling key's existing organization, not a new workspace.
• Sign in at app.formbox.ai, confirm your agency name, and open Settings / API to create an organization-bound agent key. Human passwords and agent API keys are separate credentials.
• Start with Agent — Read Only for audit/reporting, or explicitly choose the privileges needed for setup. Save keys in a password manager or protected agent environment, not chat, browser code, or source control.
• All API keys, including Admin, are scoped to their issuing workspace. Read-only access still includes Inbox contact data, file downloads, user/key metadata and delivery operations.
• Maintained Astro/WordPress adapters are privately distributed to approved operators. This product provides backend contracts, not a public form-builder or publicly installable adapter package.

Use this request to verify Hook connectivity from a trusted terminal or server.

# Run from a trusted server or terminal only.
curl "$FORMBOX_HOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-FormBox-Secret: $FORMBOX_HOOK_SECRET" \
  --data '{
    "payload": {
      "name": "Test Lead",
      "email": "test@example.com",
      "message": "Testing FormBox intake"
    }
  }'

A trusted site backend sends POST /f/{hookId}/{slug} to the intake host. JSON may contain flat business fields or a payload/metadata envelope; URL-encoded and multipart requests are also accepted.

JSON/URL-encoded bodies are limited to 64 KiB; payloads allow up to 100 fields, string values up to 10,000 characters and depth 64. Multipart uses a separate parser limit. Your hosting platform or website adapter can impose a smaller transport budget. Ordinary intake allows absent Origin/Referer, www-normalized hosts and configured wildcards. The secret is the authentication boundary; Origin is not captcha.

• The website owns field names, labels, validation, normalization, conditional logic, and required-state behavior.
• Use lowercase snake_case keys for business fields and keep the order hint aligned with the visible form.
• FormBox applies field order to notification emails, dashboard Submitted fields, API payloadFields, and CSV exports.
• Capture first-touch attribution before the visitor reaches the form and forward it as metadata, not payload.
• Supported reserved metadata fields use the _formbox_ prefix; never use that prefix for normal business fields.

• Authorization uses the Hook secret and an exact configured Origin. It is limited to five authorization attempts per Hook/IP window, independently from ordinary intake's thirty-attempt limit.
• Validate the versioned directUpload descriptor and returned policy. PUT exactly the authorized PDF to the private R2 URL within five minutes, with every returned requiredHeaders value, including if-none-match: *.
• After a successful PUT, forward _formbox_direct_upload_id with the final intake request within the thirty-minute claim window. Finalization verifies object metadata, size, type and bytes, then atomically consumes the claim with Inbox persistence.
• The final request still needs the Hook secret and normal security checks. Failed, expired, mismatched or consumed claims are not an accepted submission; retry an accepted attempt only with its unchanged Idempotency-Key.

• File bytes stay private. Dashboard downloads require workspace access; API downloads require inbox:read and return file, downloadUrl and expiresIn (300 seconds).
• Email attachment galleries use an unguessable /v/{publicId} bearer link with no login. Anyone possessing a valid link can view its submission attachments. Treat the link as sensitive; it is not indexed and the viewer is served without shared caching.
• Gallery access defaults to 30 days. Owners/managers can select 7, 14, 30, 60 or 90 days on the Hook, and authorized dashboard controls can extend or revoke access. Extending retains the public ID and restores access; do not treat the old URL as permanently dead after an authorized extension.
• Notification sends can renew expired gallery access but do not undo a manual revocation. Expiry does not delete Inbox files; authorized workspace users retain access.
• Already-issued individual file tokens have an independent 30-day expiry, and storage redirects last five minutes. Gallery revocation or expiry does not invalidate those previously issued file links. Downloaded copies cannot be revoked.

An approved webhook is an optional outbound delivery for systems that should receive only AI-confirmed legitimate submissions. It is separate from client notification email.

• Configure a public HTTPS receiver and a dedicated signing secret together.
• The signing secret is write-only, encrypted at rest, and must not reuse the public intake secret.
• Private hosts and nonpublic/local addresses are rejected. Public HTTPS IPv4 literals are permitted; DNS destinations are validated and pinned to public addresses.
• Webhooks require reviewed Legit with confidence at least 80. This is a separate gate from the email spam threshold. Spam, Suspicious, pending, failed or unavailable AI are withheld.
• Webhook attempts use durable delivery records, retry behavior, and visible submission Activity.

POST /api/v1/provision-site-intake creates one Site and between 1 and 50 Hooks in one authenticated workflow for a website integration.

Use FormBox API keys for agents and automation. Send Authorization: Bearer with the key from a protected environment. OpenAPI operations declare required scopes in x-required-scopes; successful and error bodies are specified. Management bodies reject unknown fields, invalid types and ambiguous mutations before writes.

Site creation/update supports name; an explicit null timezone clears the override, while omission retains it. Hook blank/omitted signing secret preserves the existing secret. API-key PATCH requires explicit boolean revoked: true revokes, false reinstates. User-role PATCH requires an explicit valid role; owner assignment requires literal Admin *. A key can create only a subset of its own scopes.