Embedding a Formidable form
This page documents every way to put a Formidable form on your site, and how to submit to a form directly if you're integrating without any of our scripts. It's written to be read by both people and AI coding assistants — copy-paste the snippets as-is, they only need your form's folder slug filled in.
Everywhere below, replace YOUR_FORM_FOLDER with your form's folder slug
(shown in the portal, and in the URL of the template gallery page:
https://staging.formidable.sh/t/manage/YOUR_FORM_FOLDER/). Every new form starts with
the Minimal design, so the URLs below work straight away; pick a
different design in the gallery whenever you like.
Choosing a delivery mode
There are three ways to put a form in front of users, in order of how much control they give you:
| Mode | What it is | Use when |
|---|---|---|
| Hosted page | A standalone page we host | You just need a link — email signature, social bio, QR code |
| JS embed | One <script> tag |
You're adding a form to an existing HTML page (recommended default) |
| Manual iframe | You write the <iframe> yourself |
You need control over the iframe attributes, or JS is restricted |
All three modes render the same design/theme you configured in the gallery, and all three ultimately submit to the same submission API described below.
1. Hosted page
The simplest option: a full page we host for you, with no code required.
https://staging.formidable.page/YOUR_FORM_FOLDER/
Share that URL directly, or link a button/nav item to it. Nothing to embed.
2. JS embed (recommended for most sites)
Paste this where you want the form to appear:
<div data-formidable="YOUR_FORM_FOLDER"></div>
<script src="https://staging.formidable.page/YOUR_FORM_FOLDER/embed.js" async></script>
What it does: the script finds the <div data-formidable="YOUR_FORM_FOLDER">,
creates an <iframe> inside it pointed at your form, and auto-resizes the
iframe's height to match the form's actual content (starting from a 600px
placeholder until the first resize message arrives) — no configuration
needed on your end. Everything (which form, which iframe URL) is baked into
that one embed.js URL, so the snippet is exactly two lines regardless of
your form's fields or design.
Why an iframe under the hood, instead of injecting the form's HTML straight into your page? So that anti-spam/CAPTCHA verification (Cloudflare Turnstile) keeps working without you having to pre-register your domain — the iframe's origin is always our domain, not yours.
3. Manual iframe
If you'd rather write the <iframe> yourself (e.g. you need to control
attributes we don't expose, or you can't run the embed script):
<iframe id="formidable-iframe-YOUR_FORM_FOLDER" src="https://staging.formidable.page/YOUR_FORM_FOLDER/iframe/" style="width:100%;border:0;" height="600"></iframe>
<script>
(function () {
var iframe = document.getElementById("formidable-iframe-YOUR_FORM_FOLDER");
window.addEventListener("message", function (event) {
if (event.source !== iframe.contentWindow) return;
if (!event.data || event.data.type !== "formidable:resize") return;
iframe.style.height = event.data.height + "px";
});
})();
</script>
The small <script> block is optional but recommended — without it the
iframe stays a fixed 600px tall instead of resizing to fit the form. The
form posts window.postMessage({ type: "formidable:resize", height }) to
its parent whenever its content size changes; that's the only contract the
resize script needs to honor.
Note: only the /iframe/ URL can legally sit inside an <iframe> — the
hosted page URL (the one without /iframe/) blocks framing.
4. Submitting without any embed code
If you're building your own form UI and just want to POST entries directly (a native app, a custom frontend, a script), submit to:
POST https://staging.formidable.sh/f/YOUR_FORM_FOLDER/
No API key or auth header is required — this endpoint is meant to be
called from the public internet, same as an HTML form's action URL.
Accepted content types, pick one:
- application/x-www-form-urlencoded
- multipart/form-data — required if you're uploading a file
- application/json
Fields: send the field names exactly as configured on the form. Unknown
fields are rejected (400) unless the form has schema enforcement turned
off. For a select/radio field, send one of its declared option values;
for a checkbox field with multiple values, repeat the key with []
appended, e.g. interests[]=a&interests[]=b. Required fields must be
non-empty.
CAPTCHA (only if the form has one configured): include a token field
containing the Turnstile/reCAPTCHA response token from the widget. Omitting
it returns 400. A token that fails verification is, depending on how the
service is set up, either rejected with 400 or accepted and filed as spam.
Files: send them as multipart/form-data (JSON can't carry files). Each
file has a size limit set by the form owner's plan (at most 50 MB) — a file
over it is rejected with 400 and a message saying the limit. If the owner's
plan doesn't include file uploads, or their storage is full, the submission
is still accepted but the files aren't stored (the owner sees a note on the
submission saying which files were left out).
Spam protection when hand-building your own form: the three delivery
modes above (hosted page, JS embed,
manual iframe) carry every check automatically. When you
post from your own HTML or code:
- Honeypot: add a hidden input, left empty, named after the form's
honeypot field — the name is shown on that form's manage page
(https://staging.formidable.sh/t/manage/YOUR_FORM_FOLDER/, login required). Bots that
fill it in get a normal-looking success response, but nothing is saved.
- "Sent too fast": our embeds include a signed load-time token that a
hand-built form can't reproduce, so this one check is simply skipped for
you (it never counts against you).
- Everything else still applies to every submission: per-address rate
limits, blocked IPs, content rules, throwaway email addresses, repeated
messages, and a hint for submissions sent by scripts rather than browsers
(on its own that never marks something as spam).
Submissions that look like spam are still accepted (same success response) and filed in the form's spam folder, where the owner can mark them "Not spam" — so a false positive never loses a real message.
Response, on success:
- 201 {"success": true} for forms configured to respond with JSON
- 302 redirect to the form's configured success URL (or, if you sent
Accept: application/json, 201 {"success": true, "redirect_url": "..."})
- 200 HTML "Thank you" page for forms using the default response
On failure, {"error": "<message>"} with the reason:
| Status | When |
|---|---|
400 |
Something to fix in the request: missing or invalid field, missing (or failed) CAPTCHA token, file too large, unsupported content type |
403 |
The form is switched off by its owner, or it only accepts submissions from its own website(s) and your browser request came from another site |
404 |
No form with that folder |
429 |
Too many submissions from your address in a short time (wait and retry), or the address is blocked |
503 |
Submissions are temporarily paused service-wide — retry later |
Plan limits never reject a submission. If the form owner's account is over its monthly submission limit, the submission is still accepted (normal success response) and kept; the owner sees it once they upgrade. There's no need to detect this or retry.
Example: plain HTML form, no JS
<form action="https://staging.formidable.sh/f/YOUR_FORM_FOLDER/" method="post">
<input type="email" name="email" required>
<textarea name="message" required></textarea>
<button type="submit">Send</button>
</form>
Example: curl
curl -X POST https://staging.formidable.sh/f/YOUR_FORM_FOLDER/ \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"email": "[email protected]", "message": "Hello"}'
Example: fetch, with a file upload
const formEl = document.querySelector('form');
const body = new FormData(formEl); // multipart, handles files automatically
const res = await fetch('https://staging.formidable.sh/f/YOUR_FORM_FOLDER/', {
method: 'POST',
headers: { 'Accept': 'application/json' },
body,
});
const result = await res.json();
if (!res.ok) {
console.error(result.error);
} else if (result.redirect_url) {
window.location = result.redirect_url;
}
Captcha with your own HTML
The hosted page, iframe and JS embed show the form's captcha for you -
nothing to add. The Formidable captcha only works on those pages: if a
form uses it, posts from your own HTML are refused. For your own HTML pick
Built-in only (Edit form > Spam protection), or use your own captcha
key: add
it under Captcha keys, pick it on the form, add the provider's widget inside
your <form> with the same site key, and list your domain in the key's
settings at Cloudflare/Google (as well as staging.formidable.page for the hosted page and
embeds):
<form action="https://staging.formidable.sh/f/YOUR_FORM_ID/" method="POST">
<input name="email" type="email" required>
<div class="cf-turnstile" data-sitekey="YOUR_SITE_KEY"></div>
<button type="submit">Send</button>
</form>
<script src="https://challenges.cloudflare.com/turnstile/v0/api.js" async defer></script>
The widget adds a hidden cf-turnstile-response field (reCAPTCHA:
g-recaptcha-response). Sending with your own JavaScript? Include that
field - new FormData(form) does it for you. Submissions without it are
refused with "Please complete the captcha check before sending."
Quick reference
| What | URL |
|---|---|
| Hosted page | https://staging.formidable.page/YOUR_FORM_FOLDER/ |
Iframe page (the only one embeddable in an <iframe>) |
https://staging.formidable.page/YOUR_FORM_FOLDER/iframe/ |
| JS embed script | https://staging.formidable.page/YOUR_FORM_FOLDER/embed.js |
| Submission endpoint | POST https://staging.formidable.sh/f/YOUR_FORM_FOLDER/ |
| Pick a design / delivery mode (requires login) | https://staging.formidable.sh/t/manage/YOUR_FORM_FOLDER/ |
Machine-readable version of this page: https://staging.formidable.sh/docs/embed.md — plain markdown, safe to fetch and parse programmatically.