Headless

Headless lets you build your own form interface and send submissions to Makeform for validation, storage, and routing. Use it when you want control over the form experience or need to submit from a server.

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.

A Headless endpoint is a public POST URL tied to one form. Each form can have one endpoint. Submit responses to https://submit.makeform.ai/f/ENDPOINT_ID, using the endpoint ID, not the form ID. MCP tools return the endpoint ID and submit URL.

A Headless form has no hosted page and starts in loose schema mode. You can also add an endpoint to a hosted Page form; that endpoint starts disabled and must use strict mode.

Strict mode rejects unknown keys and enforces field types and options. Loose mode accepts unknown keys and learns them into the form's schema.

Use a browser request when your endpoint allows the page’s origin. Use a server request when you want to keep a backend key on your server. Server requests must omit the Origin header. If Origin is present, browser authorization applies and any backend key is ignored. A Headless key is scoped to one endpoint and differs from a management API key. The form must be published, and an endpoint needs at least one allowed origin or a backend API key before you can enable it.

Headless requests accept application/json and application/x-www-form-urlencoded, with a 256 KB body limit. File uploads are not supported. A hosted Page form with hosted CAPTCHA enabled cannot accept Headless submissions; it returns 403 with code captcha. CAPTCHA is a form setting, not a field.

Submit a response

This server request omits the Origin header and uses a Headless key. Replace ENDPOINT_ID with the endpoint ID and use your own field names and answers.

curl https://submit.makeform.ai/f/ENDPOINT_ID \
  -H "Authorization: Bearer mfh_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ada Lovelace","email":"[email protected]","message":"Please send me the product guide."}'

A successful submission returns:

{
  "ok": true,
  "message": "Submission successful!",
  "submissionId": "SUBMISSION_ID"
}

Plan limits

	Free	Pro and Business
Enabled endpoints	1	Unlimited
Headless submissions per month	50	Unlimited
Respondent auto-reply	No	Yes
Respondent email verification	No	Business only

Enabling a second endpoint on Free returns 403. When the submission quota is reached, submissions return 429 with code quota; retryAfter gives the number of seconds until the next UTC month, and the response includes a Retry-After header. Respondent email verification is browser-only. While verification is required, backend-key submissions return 403 with code email_verification.

Headless topics

Create and configure an endpoint
Submit a response
Choose strict or loose schema mode
Authenticate browser and server requests
Understand responses and errors
Use idempotency for safe retries
Spam protection and rate limits
Plan limits
Auto-replies, notifications, and integrations
Verify respondent email addresses
Save partial submissions
Use the embed.js helper with hand-written HTML forms

Partial saves require a hosted Page form, strict mode, an allowed browser origin, JSON, and enabled partial submissions. Headless forms receive 403 with code unsupported. Headless forms have no hosted embed; the embed.js helper for hand-written forms does not render or style forms.