Developer Platform

Outside form submissions

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

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. For exact current technical availability, use the generated API Map and first-class module inventory.