Headless idempotency keys

Use an idempotency key when you submit a Headless form so you can retry the same request and receive the original submission ID.

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.

Send an idempotency key

Send the key in the Idempotency-Key header or as _idempotency_key in the request body. A key must be 8–128 characters and use only letters, digits, ., _, : or -. If you send it in both places, the values must match.

curl -X POST https://submit.makeform.ai/f/ENDPOINT_ID \
  -H "Authorization: Bearer mfh_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-attempt" \
  -d '{"name":"Ada","email":"[email protected]"}'

A successful first submission returns its submission ID:

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

If you need to retry, send the same request with the same key. The replay returns the original submissionId without a message:

{
  "ok": true,
  "submissionId": "SUBMISSION_ID"
}

Use a new key for a different request. Reusing a key with a different payload returns 409:

{
  "ok": false,
  "error": "This submission key was already used. Use a new key for different answers.",
  "code": "idempotency_conflict"
}

Errors

Status	Code	When
400	`idempotency_key_invalid`	The key is invalid, or the header and body keys do not match
409	`idempotency_conflict`	The key was already used with a different payload
503	`idempotency_unavailable`	Idempotency is unavailable