# HTML form

Use a plain HTML form on your own site to send answers to an InvoyForm form: the endpoint, the field names, what comes back, and the limits.

Build the form with InvoyForm, then post to it from a form you wrote yourself. You control the markup and the CSS. InvoyForm checks the answers and stores them.

## The form

Publish the form, open **Share**, and copy the **HTML form**. It looks like this:

```html
<form action="https://form.invoy.in/api/public/headless/forms/YOUR_FORM_ID" method="POST">
  <label>
    Full name
    <input type="text" name="full_name" required>
  </label>
  <label>
    Email
    <input type="email" name="email" required>
  </label>
  <button type="submit">Submit</button>
</form>
```

It has your questions' help text, their starting values and the button text you chose in Settings. It is a starting point. Change the markup and style it as you like, but keep each field's `name`.

## Allowed websites

Your form's id is in the HTML code you put on your page, so anyone who sees it could use your form from their own site. To stop that, a form works only on websites you allow. Your form's own link always works.

Open **Settings** in the builder, add the websites where you use the form, and publish. Only those websites can show the form in a frame (an embed) or send answers from their own HTML form or script. Posts from anywhere else, including a script with no website behind it, are refused with a `403`.

- `my-site.com` allows that site only. `www.my-site.com` is another site: add it too, or add `*.my-site.com` for all its subdomains.
- The site must use `https`. `localhost` (to test on your machine) always works.
- The list takes effect when you publish.

## The script

The code from Share also has a `<script>` line and `data-ivf` on the form:

```html
<form action="https://form.invoy.in/api/public/headless/forms/YOUR_FORM_ID" method="POST" data-ivf>
  ...
</form>
<script src="https://form.invoy.in/v1/embed.js" defer></script>
```

With it the page does not reload. The script sends the form, turns the button off while it works, shows each answer that is not accepted under its field, and shows a thank-you when it is done. Without it the form still works as a normal post.

You can shape it with attributes. None are needed.

| Attribute | What it does |
| --- | --- |
| `data-ivf-error="email"` on any element in the form | Shows the message for the field `email` there, instead of adding one under the field |
| `data-ivf-form-error` on an element | Shows messages that are about the whole form (too many attempts, no connection) |
| `data-ivf-success` on a hidden element | Shown instead of the default thank-you |
| `data-ivf-redirect="https://..."` on the form | Goes to that address after a successful send. Without it, the form's own redirect address (if you set one for the form) is used |
| `data-ivf-state` on the form (set by the script) | `idle`, `submitting`, `error` or `success`, for your CSS |

Added messages have the class `ivf-error` (the thank-you has `ivf-success`) and a plain default look. Style them with your own CSS. A field with a message has `aria-invalid="true"`.

The script uses the browser's own checks (`required`, `type`, `min`, `max`...) and shows them in the same place. Every other rule is checked by InvoyForm after the send.

### Events

The form tells your page what happened, so your code can close a dialog, track a conversion or show its own message. Both events bubble.

| Event | When | `event.detail` |
| --- | --- | --- |
| `ivf:success` | The answers were accepted | `{ redirectUrl }`, where the person is sent next, if anywhere |
| `ivf:error` | The answers were not accepted | `{ errors: [{ field, message }] }`, or `{ message }` for the whole form |

```js
form.addEventListener('ivf:success', () => closeDialog());
```

### React, Vue and other frameworks

The script also finds forms that appear after the page has loaded, like a form in a dialog or on a page your router shows later. Load the script once, render the form with `data-ivf`, and let it submit natively: no `onSubmit` handler and no state for the values. To have your agent do it for you, see [Build it with your AI agent](https://form.invoy.in/docs/developer/ai-agents/).

If your site sends a Content Security Policy, allow `https://form.invoy.in` in `script-src` (the script) and `connect-src` (where it sends the answers), and in `frame-src` if you use the [embed](https://form.invoy.in/docs/developer/embed/).

## Field names

Every field that takes an answer has a `name`, made from its label as you build ("Full name" becomes `full_name`). A repeated name gets `_2`, `_3`. A field with no label uses its placeholder, then its type. You can change a name in the field's **Advanced** tab.

- Post each answer under its field's `name`.
- A group of checkboxes shares the field's name with `[]`: `name="interests[]"`.
- A group of radio buttons shares the field's name.
- A phone question is `type="tel"`. The number has to start with the country code and a plus, like `+1 415 555 2671`; spaces, dashes and brackets are fine.
- A date question is `type="date"`, written `2026-11-10`. A time question is `type="time"`, written `14:30` on a 24-hour clock. A date and time question is `type="datetime-local"`, written `2026-11-10T14:30`; the time zone is left out of a plain post.
- A URL question is `type="url"`, and the address starts with `http://` or `https://`.
- A checkbox question posts `true` when it is ticked and nothing when it is not.
- A rating or a linear scale is a group of radio buttons whose values are the numbers, like `1` to `5`.
- A grid posts each row under a name of its own, the field's name with `.` and the row's id: `name="rooms.opt_row1"`. A multiple choice grid has one radio group for each row; a checkbox grid names each row `rooms.opt_row1[]`. The HTML from Share has them all.
- A question with an Other option has one more choice, `value="__ivf_other__"`, and a text box named after the field with `.other` added: `name="source.other"`. What is written in the box is the answer. The HTML from Share has both.
- Once the form is published a name stays as it is, even if you edit the label. Change it yourself in the Advanced tab if you must, and update the HTML forms that use it.

Names that start with `_ivf_` are InvoyForm's own, never a field's. They are not kept with the answer. Any other name that starts with `_` is refused.

| Name | What it is |
| --- | --- |
| `_ivf_password` | The form's password, when it has one. Let the respondent type it: `<input type="password" name="_ivf_password">`. Never put it in the page's HTML, where anyone can read it. A script that sends the answers itself can send it this way too. |

## Spam protection

Every form has basic spam protection. The HTML from Share includes a small hidden part for it, which a person never sees. If you change the markup, keep it in the form.

On the Pro plan and up you can give the hidden input a name of your own, in the builder's **Settings**, under **Spam protection**. It applies when you publish. Copy the HTML from Share again then, or change the name in your page: an input with the old name is no longer a trap.

To add a captcha to a form on your own site, use your own Cloudflare Turnstile widget (add your site's address to its hostnames). In the builder's **Settings**, under **Spam protection**, turn on **Captcha on your own site** and choose it, or add it with the **+** button: give its site key and secret key. Publish, then copy the HTML from Share again: it now has the widget. Answers without a passed check are refused with a message to complete it. The secret key stays with us and is never shown again.

## After you submit

- A browser that posts the form lands on the form's thank-you page, in the form's theme, or on the form's redirect address if you set one.
- If an answer is not accepted, the browser is sent back to the form page with the questions that need another look marked. The form is empty again (what was typed is never kept in the address), so the respondent fills it in again.
- If the form as a whole does not take it (the captcha was not passed, the website is not allowed, the form is closed or full), the browser lands on a page that says why, with a **Go back** button to your form. With the Invoy script, the same words show in your page instead, in an element with `data-ivf-form-error`.
- A script (`fetch`, `curl`) gets JSON back instead.

For a script, an answer that is not accepted is a `400`, and `details` says which field:

```json
{
  "success": false,
  "message": "Some of the answers need another look.",
  "details": [
    { "field": "email", "message": "Please enter a valid email address." }
  ]
}
```

`field` is the field's `name`.

## Files

A form with a File Upload question gives you an `<input type="file">`. Only the Invoy script can send it (the HTML from the Share page includes it): it sends each chosen file first, then posts the form with the files' ids in their place. A plain form without the script cannot send files.

If a file is not accepted (too big, a kind the question does not take), the message shows next to its field.

## Limits

- The generated HTML is a copy. If you add a required field to the form later, copy the HTML again, or posts without that field are rejected.
- Logic (showing a field only when another has a value) and widgets that need JavaScript are not part of the plain HTML.
- Your plan sets how many HTML posts a month a workspace can receive.
