Skip to content
Docs menu

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.


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.