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:
| Limit | Default |
|---|---|
| Fields | 50 |
| Characters per field | 5,000 |
Nesting depth (name="address[town]") | 3 |
| Request body, without files | 512 KB |
A submission with every field empty is rejected.
Reserved names
FormHam uses these itself. They are not stored as your data:
| Name | What it does |
|---|---|
_gotcha, _honeypot, honeypot | Honeypot. See below. |
_source_url | The page the form was on. Stored. If absent we use the Referer or Origin header. |
_page_title | The page's title. Stored and shown with the submission. |
_idempotency_key | Up to 120 characters. A retry with the same key returns the original submission instead of creating a second one. |
_locale | Language for FormHam's own responses (the thank-you page and error messages). |
g-recaptcha-response | reCAPTCHA token. Verified, then discarded. |
_fh_pow | The built-in spam check's answer, added by the embed script. |
_token, _method | Discarded. |
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
| Status | Meaning |
|---|---|
| 403 | Refused: the form is inactive or does not exist, the domain is not allowed, or spam protection rejected it. |
| 422 | Invalid: honeypot filled, empty submission, too many fields, nested too deep, or a rejected file. |
| 429 | Too many requests: 5 per minute from one IP to one form, or 60 per minute to one form; or the account's monthly limit. |
| 503 | Accepted 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 protection | Plain 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 reCAPTCHA | No 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). |
| Both | As Google reCAPTCHA. |
| Off | Accepted. |
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.