Headless HTML forms

Use a Headless endpoint when you want to write your own HTML form and send submissions to Makeform. The optional embed.js script connects your form to the endpoint.

Beta

This feature is available to all accounts. Its request and response format can change without a new API version. Do not depend on it for anything you cannot update quickly.

Add the script to your form

Set data-makeform to the endpoint ID or full submit URL. Use the endpoint ID, not the form ID. Add embed.js to the page:

<form data-makeform="ENDPOINT_ID">
  <label>
    Name
    <input name="name" required>
  </label>

  <label>
    Email
    <input name="email" type="email" required>
  </label>

  <button type="submit">Send</button>
  <p data-makeform-status></p>
</form>

<script async src="https://submit.makeform.ai/embed.js"></script>

The form must be published, and its Headless endpoint must be enabled. For browser submissions, the page’s origin must be allowed by the endpoint.

What the script handles

The script binds every form[data-makeform] on the page. It sends the form as JSON, adds attribution and an idempotency key, and adds a hidden _gotcha input if the form does not already have one.

While sending, it disables submit buttons and times out after 15 seconds. On success, it resets the form and shows status text in the [data-makeform-status] element, creating that element if needed. If a field is invalid, the script marks it with aria-invalid="true", then focuses and scrolls to the first invalid field.

Checkbox groups and select[multiple] values are sent as arrays. File inputs are skipped; Headless endpoints do not support file uploads. The script does not render or style your form.

Update forms after page changes

If your page adds forms after the initial load, call window.MakeformHeadless.init() to bind them. It is safe to include the script more than once.

You can set these attributes on the form to customize its states:

Attribute	Purpose
`data-sending`, `data-success`, `data-error`	Sending, success, and error states
`data-redirect`	Client-side redirect after success
`data-code-sent`, `data-email-verified`, `data-verification-error`	Email verification states

Use data-makeform-status on an element to show status text. The script also supports email verification and Turnstile elements through data-makeform-verify-email, data-makeform-send-code, data-makeform-code-input, data-makeform-verify-code, and data-makeform-turnstile (or the cf-turnstile class).