Ingest contract

This is the full reference for the submission endpoint, POST /f/:formId. Production base URL: https://forms.formward.eu. A machine-readable OpenAPI 3.1 fragment is published at /docs/openapi. For the higher-level walkthroughs, see Responses & redirects and File uploads.

Accepted content types

The endpoint accepts a submission body in any of three encodings:

• application/x-www-form-urlencoded — a classic HTML form POST.
• multipart/form-data — required when the form uploads files. File handling (count, per-file size, total size, and the MIME allowlist) is documented in File uploads.
• application/json — the body must be a JSON object. Arrays, strings, numbers, and null are rejected with 400. An empty body is treated as no fields.

Whatever the encoding, fields are flattened into one payload object before any checks run, so behaviour is identical across encodings.

Classic vs AJAX is content-negotiated

The endpoint decides between a classic (redirect / HTML) and an AJAX (JSON) response from the request headers. A request is treated as AJAX when its Accept header includes application/json, or when it carries an X-Requested-With header. Otherwise it is treated as a classic form post. This applies to both success and error responses.

Success responses

The AJAX id is the stored submission ID and files is the number of attachments stored. Redirect-target resolution and the default /thanks behaviour are covered in detail in Responses & redirects.

Error table

In AJAX mode each error returns the JSON body shown below. In classic mode the same status code is returned with a minimal HTML error page instead.

The over-quota 402 respects your plan's overage buffer: submissions are accepted (and metered as overage) up to the buffered ceiling before the endpoint starts returning 402. Spam and rate-limited requests are gated earlier and never consume quota.

CORS

The endpoint is CORS-aware so a cross-origin browser fetch() can read the JSON response:

• Preflight: a non-simple cross-origin request (for example one sending Content-Type: application/json or an X-Requested-With header) triggers an OPTIONS preflight. The endpoint answers 204 with Access-Control-Allow-Methods: POST, OPTIONS and Access-Control-Allow-Headers: content-type.
• Access-Control-Allow-Origin reflects the request Origin only when that origin is permitted by the form's allowed-origins list (the same gate as the 403 origin not allowed check), with Vary: Origin. A disallowed origin gets a 204 preflight without the allow-origin header, so the browser blocks the real request.
• A form with an empty allowed-origins list is treated as public: the origin is reflected (or * when there is no Origin header).

Honeypot

Include a hidden _gotcha field. Any submission where _gotcha is non-empty is silently stored as spam and returns a success-shaped response (a 200 { ok: true, files: 0 } in AJAX mode, or a redirect / thanks page in classic mode) so bots get no signal. It does not send a notification email or consume quota. The same indistinguishable-success behaviour applies to senders matched by a form's block list. See Special fields for the recommended hiding technique.

Control fields

Fields whose names start with an underscore are control fields: they are read for their effect and stripped before the payload is stored or emailed.

Minimal AJAX example

const res = await fetch("https://forms.formward.eu/f/<formId>", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Accept": "application/json",
  },
  body: JSON.stringify({
    email: "visitor@example.com",
    message: "Hello",
    _consent: "true", // only if the form requires consent
  }),
});
const data = await res.json(); // { ok: true, id, files } on success