Documentation
Options reference
Every field, header and configuration option in one place: what it does, where it goes, and what type it expects. Use this as a lookup; the other pages explain the reasoning behind each one.
Last updated
Submission fields
Sent in the body of a POST to your form's endpoint. Field names starting with an underscore are directives, not stored as submission data. See special fields for the fuller explanation.
| Name | Type | Where | Description |
|---|---|---|---|
access_key | string | body | Your form's public key, if not already in the URL path. Prefer the URL form (send.webforms.to/wft_...). This exists for clients that can't easily set a dynamic action URL. |
_next | URL | body | Redirect the browser here after a successful submission. Must be a full https:// URL. |
_redirect | URL | body | Alias for _next. Also used on a validation failure to redirect back with ?wf_error=... appended, so you can show the error inline on your own page. |
_subject | string, max 300 | body | Overrides the notification email's subject line. |
_from_name | string, max 120 | body (Pro/Agency) | Overrides the display name the notification email appears to come from. Only applies on plans with custom sender names; ignored on Free. The sending address itself never changes. |
_replyto | body | Sets Reply-To on the notification email, so replying goes straight to your visitor. There is no per-submission CC field: CC and BCC recipients are configured per email destination in the dashboard (paid plans), and the notification template is chosen per form (see notificationTemplateId below). | |
_page | URL, max 2000 | body | Full URL of the page the form is on. Shown as “Submitted from” in the notification email. Falls back to the Referer header if omitted, but a cross-origin POST's Referer is stripped to bare origin by the browser. Set this to get the actual page instead of just the domain. |
_gotcha | any | body | Honeypot field. Leave it out of your visible markup, hidden with CSS. If a bot fills it in, the submission is silently dropped and the bot still sees a normal success response. |
_start_time | unix ms | body | Set via JS when the form renders. Submissions arriving faster than the configured minimum fill time are treated as bots. |
_test | boolean | body | Marks the submission as a test. Stored, delivered and counted toward your monthly quota like any other, but left out of the default Submissions API listing. |
_captcha, cf-turnstile-response, h-captcha-response, g-recaptcha-response | string | body | Captcha verification token, whichever field name your captcha provider's widget produces. |
Headers
| Name | Type | Where | Description |
|---|---|---|---|
content-type | header | request | application/x-www-form-urlencoded, multipart/form-data (required for file uploads), or application/json. |
accept | header | request | Send application/json to get a JSON response instead of the default HTML success/redirect flow. |
Idempotency-Key | header, any string | request | A repeat POST with the same key returns the original result instead of creating a second submission. Safe to set on every request from a client that might retry on a network error. |
Authorization / X-API-Key | header, Bearer wf_live_... | request (APIs) | Required on every Submissions API, write API and MCP request. Never required on the public ingest endpoint. |
X-RateLimit-Limit / -Remaining / -Reset | header | response | Present on every authenticated API response, so a client can back off before it gets a 429 rather than after. |
X-WebForms-Timestamp / X-WebForms-Signature | header | webhook delivery | Present on signed webhook deliveries. See webhook signing. |
Form settings
Configured once in the dashboard, or via PATCH /v1/forms/:id.
| Name | Type | Where | Description |
|---|---|---|---|
name, description, isActive | string / string / boolean | form | Basic identity. An inactive form's endpoint refuses submissions with form_not_found. |
fields | array | form | Declared field schema (name, type, required, min/max, pattern, options). Drives server-side validation. An empty array plus allowExtraFields accepts anything. |
allowExtraFields | boolean | form | Whether fields not declared in fields are accepted (true) or rejected as validation_failed (false). |
confirmation.redirectUrl | URL | form | Where a browser submission redirects on success. Same effect as _next but set once on the form instead of per-request. Free on every plan. |
confirmation.successMessage | string | form | Custom text shown on the default HTML success page when no redirect is set. Free on every plan. |
confirmation.thankYouTitle | string, max 100 | form (Pro/Agency) | Replaces the default “Thanks!” heading on the built-in confirmation page. |
confirmation.forceJson | boolean | form (Pro/Agency) | Always respond with JSON on a successful plain-form submit, even without an Accept header. A redirect (from _redirect, _next, or confirmation.redirectUrl) still wins over this. |
confirmation.customJsonSuccess | object of string:string, up to 20 entries | form (Pro/Agency) | Extra fields merged into the JSON response on a successful submit. Key names cannot collide with a field the response already sends (ok, id, alert, message, and so on). |
confirmation.customJsonError | object of string:string, up to 20 entries | form (Pro/Agency) | Same as customJsonSuccess, merged into the JSON body on validation failure or another error response. |
notificationTemplateId | string | form | Which template renders the delivery email: a built-in id, or a custom template's id. |
autoResponder.enabled / subject / body / fromName | boolean / string / string / string | form | The confirmation email sent back to the person who submitted, separate from your own notification. |
allowedOrigins | string[] | form (Pro/Agency) | Hostnames (or *.example.com wildcards) allowed to submit to this form. A request from anywhere else is refused before it is validated or stored. |
uploads.allowFileUploads / maxFileSizeMb / allowedFileTypes | boolean / number / string[] | form | See file uploads for limits and blocked-extension detail. |
Spam configuration
The spamConfig object accepted by the same PATCH endpoint. Full scoring model and worked examples on the spam protection page.
| Name | Type | Where | Description |
|---|---|---|---|
honeypot | boolean | spamConfig | Turn the honeypot trap on or off. The field it checks is always _gotcha. |
timeTrapMs | number, default 2000 | spamConfig | Minimum time between the form rendering (_start_time) and the submission arriving. Faster is treated as a bot. |
captcha | "none" | "turnstile" | "hcaptcha" | "recaptcha" | spamConfig | Which captcha provider's token to verify server-side, if any. |
aiClassifier | boolean | spamConfig | Run submission content through the AI spam classifier as an additional signal. |
threshold | number 0-1, default 0.6 | spamConfig | Combined score at or above this is quarantined rather than delivered. |
blockedDomains / blockedKeywords | string[] | spamConfig | Exact-match email domains and keywords that add to the score. |
blockDisposableEmail | boolean, default true | spamConfig | Flag known disposable/temporary email domains. |
Get your endpoint
Free for 300 submissions a month. No card required.
Start free