Request body

Customer-defined fields, reserved control fields and payload limits.

The API does not fix a global field schema. The customer’s form defines the fields, and the form settings may enforce required fields or an allowed field name list.

Example

{
  "name": "John Smith",
  "email": "[email protected]",
  "phone": "0400000000",
  "message": "I'd like more information",
  "cf-turnstile-response": "TURNSTILE_TOKEN"
}

Reserved control fields

FieldBehaviour
cf-turnstile-responseTurnstile token. Required only when Turnstile is enabled. Stripped before storage and email.
_honeypotMust be empty. If filled, returns a generic 403 verification_failed and stores no payload.
_idempotency_keyHTML-form alternative to the Idempotency-Key header. Must match the header if both are supplied.

Other underscore-prefixed fields are rejected. Client-supplied recipients, headers, redirect destinations and webhook destinations are never honoured.

Value rules

  • At least one non-empty business field is required.
  • Scalars may be strings, numbers or booleans. Legitimate 0 and false values are preserved.
  • Lists are allowed up to 20 scalar items.
  • Nested objects and files are rejected.
  • Field names are limited to 100 characters.
  • Each scalar value is limited to 10,000 characters.
  • A request may contain up to 50 fields.
  • The total body is limited to 64 KiB.

Payload limits

Request body
64 KiB
Fields per submission
50
Field name length
100
Scalar value length
10,000
List items
20
Idempotency key
128 chars

Rate limits

Per IP, per form
10/min
Per IP, all forms
60/min
Per form
120/min
Global
600/min
CORS preflight
120/min
Retention
90 days

Form-specific validation

A form may configure:

  • required fields;
  • an allowlist of field names;
  • field labels and display order for the notification email.

These rules are enforced server-side. The public API returns safe field errors with 422 validation_failed.