Docs

HTML forms

Any HTML form can post to FormHam. No JavaScript is required, although adding the embed makes spam checks and the thank-you message smoother.

The action URL

Post the form to your form's endpoint, shown on its General tab:

<form action="https://app.formham.co.uk/submit/YOUR-FORM-ID" method="POST">

https://app.formham.co.uk/forms/YOUR-FORM-ID/submit is accepted too and behaves identically; it exists for older plugin versions. The method must be POST — opening the endpoint in a browser (a GET) just tells you so.

Naming fields

Every control needs a name. A field without one, or with name="", is discarded by the browser before the request is sent, so it never reaches us and nothing can warn you — this is the most common way a form silently loses data. Whatever names you use are stored as they are; there are no required field names. Two are worth using:

  • email — lets you send an auto-reply to the person who filled the form in, and lets a subject access or erasure request find their submissions.
  • name — shown in your dashboard. A link in the name field is a classic spam signature, so a submission with one is held for review whatever spam mode the form uses.

Limits, per submission:

LimitDefault
Fields50
Characters per field5,000
Nesting depth (name="address[town]")3
Request body, without files512 KB

A submission with every field empty is rejected.

Reserved names

FormHam uses these itself. They are not stored as your data:

NameWhat it does
_gotcha, _honeypot, honeypotHoneypot. See below.
_source_urlThe page the form was on. Stored. If absent we use the Referer or Origin header.
_page_titleThe page's title. Stored and shown with the submission.
_idempotency_keyUp to 120 characters. A retry with the same key returns the original submission instead of creating a second one.
_localeLanguage for FormHam's own responses (the thank-you page and error messages).
g-recaptcha-responsereCAPTCHA token. Verified, then discarded.
_fh_powThe built-in spam check's answer, added by the embed script.
_token, _methodDiscarded.

We also record the IP address the submission came from, as _ip. It appears in the dashboard and in webhook payloads.

What happens after submit

For an ordinary form post (no JavaScript):

  • If the form has a Redirect URL (its General tab), the visitor is redirected there. Use it to send people to your own thank-you page, for example https://example.com/contact?sent=1#thanks — the URL is used exactly as you enter it.
  • Otherwise they see FormHam's plain confirmation page, with a receipt reference and a link back to the page they came from.

There is no hidden field that sets the redirect per submission: _redirect, _next and similar names are stored as ordinary data. The destination is a setting on the form, so a third party cannot use your endpoint to bounce visitors somewhere else.

If the request sends Accept: application/json — as the embed script does — you get JSON back instead:

{
  "message": "…",
  "redirect_url": "https://example.com/thanks",
  "submission_id": 4182,
  "receipt_id": "…",
  "idempotent_replay": false,
  "status_url": "…"
}

Errors

StatusMeaning
403Refused: the form is inactive or does not exist, the domain is not allowed, or spam protection rejected it.
422Invalid: honeypot filled, empty submission, too many fields, nested too deep, or a rejected file.
429Too many requests: 5 per minute from one IP to one form, or 60 per minute to one form; or the account's monthly limit.
503Accepted for later processing. The body includes a receipt_id; retry with the same idempotency key and you will not create a duplicate.

Honeypot

Add a field that people cannot see and bots will fill in. If it arrives with a value, the submission is rejected and nothing is stored. Hide it with CSS, not type="hidden", and keep it out of the tab order:

<div style="position:absolute;left:-9999px" aria-hidden="true">
  <input type="text" name="_gotcha" tabindex="-1" autocomplete="off">
</div>

The embed script adds one of these for you.

File uploads

Uploads are switched off by default and are enabled per account and per form on request. Where they are on, post the form as multipart/form-data:

<form action="https://app.formham.co.uk/submit/YOUR-FORM-ID" method="POST" enctype="multipart/form-data">
  <input type="file" name="attachment">
  …
</form>
  • Up to 5 files, 10 MB each, 25 MB per submission.
  • Allowed types: PDF, Word (doc, docx), ODT, RTF, TXT, JPEG, PNG, HEIC and WebP. Both the file extension and the file's actual content are checked.
  • Every file is virus-scanned before it is stored. If scanning is unavailable the upload is refused, not accepted unscanned.
  • A file sent to a form that does not accept uploads is rejected with a 422 rather than silently dropped.
  • Files are stored privately and downloaded through short-lived links that also require you to be signed in.

Allowed domains and CORS

With Domain locking on (the form's Security tab), only the domains in Allowed domains are accepted. A bare domain includes its subdomains, and *.example.com works too. When you sign up, the site domain you enter is added to your account's allowed domains. A browser submission from a domain that is not allowed is held for review rather than discarded, so a typo in the list costs you a click, not a lead.

Cross-origin requests are answered with the requesting origin reflected back, for POST, GET and OPTIONS. If you post with fetch from your own code, send the idempotency key as the _idempotency_key body field rather than a custom header.

Without JavaScript: what each spam mode does

The honeypot, domain lock and rate limits apply in every mode. What changes is how a plain HTML post, with no script on the page, is treated:

Spam protectionPlain HTML post, no JavaScript
Built-in check (the default)Accepted if it comes from your own site with nothing else suspicious about it. A missing answer counts against it, so any other warning sign — no Origin header, an untrusted origin, promotional content — puts it in quarantine for you to review.
Google reCAPTCHANo token is sent, so the submission cannot be verified. If the browser says it came from one of your domains it is held for review; otherwise it is refused (403).
BothAs Google reCAPTCHA.
OffAccepted.

For the best results on a hand-written form, add the embed script: it answers the built-in check or fetches the reCAPTCHA token for you, and the plain post still works for anyone with scripting off.