---
title: "Outside form submissions"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/outside-form-submissions.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Outside form submissions

Configure tenant-owned form endpoints and receive server or browser submissions in Universal Inbox.

## In brief

- **Configuration owner:** Tenant organization owner
- **Submission modes:** Server secret or public browser
- **Record boundary:** Personal or DataRole + optional location

An outside form endpoint accepts a JSON or URL-encoded POST from a site or external server and creates an organization-scoped source record plus a Universal Inbox item. Each endpoint is configured by its tenant organization owner. The incoming item receives the configured **Personal** owner or **DataRole** and optional location at creation; the sender cannot choose or override that visibility. Inbox is the attention layer, not a separate form-record database.

You can use any existing HTML form or trusted server form; BuildWithHQ does not require a form builder or a predefined field schema. Submit ordinary named fields, then open the resulting Universal Inbox item to see a secured table of each submitted key and value. The original submission remains a native source record. A user can ask GoClaw to propose a Contact or other action from it, subject to the normal permission and approval policy; the POST itself does not automatically create a Contact.

## Configure an endpoint

The owner chooses a unique `endpointKey` (lowercase letters, digits, period, underscore or hyphen; at most 100 characters), display name, mode, and target. Exactly one target is required: `ownerUserId` for Personal, or `targetDataRoleId` for a shared role. `locationId` is optional for role targets. A public-browser endpoint also needs one exact HTTPS `allowedOrigin`; server-secret endpoints must not set it. A disabled endpoint rejects new submissions. Updating requires the current `expectedRevision`; a conflict means reload before retrying.

The tenant UI uses `GET /api/outsideformsubmissions/endpoints`, `POST /api/outsideformsubmissions/endpoints`, and `PUT /api/outsideformsubmissions/endpoints/{endpointId}` on the tenant hostname. The public Developer API exposes the corresponding routes under `/v1/apps/{saasAppId}/outsideformsubmissions`, with `GET /endpoints`, `POST /endpoints`, and `PUT /endpoints/{endpointId}`. Management requires a **delegated active tenant-owner** credential with `outside-forms.manage`; a server-held app credential, scope alone, or a supplied owner ID does not confer ownership. The list is bounded to 100 entries per page. Create does not accept `expectedRevision` or `rotateSecret`; those are update-only controls. `GET /browser-challenge` returns the public Turnstile site configuration, and `GET /{submissionId}` reads one authorized submission. A server secret appears only on server-mode creation, explicit rotation, or changing a browser endpoint into server mode; list and ordinary update responses never include it. A lost secret cannot be read back and must be rotated.

## Server-to-server POST

Send to `https://{tenant-host}/api/outsideformsubmissions/server/{endpointId}` with `Content-Type: application/json` or `application/x-www-form-urlencoded`, a fresh GUID `Idempotency-Key`, and the `X-Outside-Form-Secret` header. The 64-character secret is returned only when created or explicitly rotated. Store it server-side; never embed it in HTML, JavaScript, or a public repository. A first accepted submission returns 201; an idempotent replay returns 200 with the same receipt.

## Public-browser POST

Send to `https://{tenant-host}/api/outsideformsubmissions/browser/{endpointId}` from the endpoint's configured exact HTTPS origin. Include a GUID `Idempotency-Key` and a fresh Cloudflare Turnstile token in `X-Turnstile-Token` (or `cf-turnstile-response` for an HTML form). The widget uses action `outsideformsubmissions`. The server verifies the token, hostname, action, and allowed origin; a missing provider configuration or invalid challenge fails closed. Operators must configure the site key, server-side secret, and permitted form hostname before browser submissions can work. CORS preflight allows only the configured origin and submission headers.

## Limits and security

Payloads are capped at 64 KiB, JSON depth four, and 100 form fields. Form keys cannot set tenant, user, DataRole, location, or other authorization identity. Do not treat a successful POST as permission to read the created record: normal secured-record procedures still enforce tenant, DataRole/Personal, and location access. The API returns safe error codes and a correlation ID; do not log secrets or challenge tokens.

The Developer Kit includes the management operations and these submission instructions, but public submissions go to the *tenant hostname*, not `api.buildwithhq.com`. This separation lets external servers use a narrow secret and browsers use an anti-spam challenge without exposing a Developer API key.

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/outside-form-submissions.html).