# 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](#1-hosted-page) | A standalone page we host | You just need a link — email signature, social bio, QR code |
| [JS embed](#2-js-embed-recommended-for-most-sites) | One `<script>` tag | You're adding a form to an existing HTML page (recommended default) |
| [Manual iframe](#3-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](#4-submitting-without-any-embed-code)
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:

```html
<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):

```html
<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](#1-hosted-page), [JS embed](#2-js-embed-recommended-for-most-sites),
[manual iframe](#3-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

```html
<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

```bash
curl -X POST https://staging.formidable.sh/f/YOUR_FORM_FOLDER/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "jane@example.com", "message": "Hello"}'
```

### Example: fetch, with a file upload

```js
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):

```html
<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](https://staging.formidable.sh/docs/embed.md) — plain markdown, safe to fetch and parse programmatically.*
