Submit form

Submit a customer-defined set of fields to a public form.
POST/v1/forms/{public_id}/submissions Primary

Submit a form

Submits a customer-defined set of fields to a public form. This is the primary versioned endpoint; POST /f/{public_id} is a short alias with identical behaviour. The request must include an allowed Origin. Turnstile is required only when the form has Turnstile enabled. JSON clients should send Accept: application/json. Native HTML forms receive a 303 redirect on success. A successful JSON response means the submission is durably stored and scheduled, not that email has reached an inbox.

https://api.postvia.dev/v1/forms/abc123/submissions

Headers and parameters

Name In Required Description
public_idpathRequiredOpaque public form identifier. Treat it as an identifier, not an authentication secret.
Example: abc123
AcceptheaderOptionalOptional. Use application/json to receive a JSON response. Native HTML submissions receive a 303 redirect.
Example: application/json
Idempotency-KeyheaderOptionalOptional key for safe retries. Reuse the same key while the payload is unchanged. Maximum 128 characters.
Example: 550e8400-e29b-41d4-a716-446655440000
OriginheaderRequiredRequired. The canonical origin of the customer website. It must be on the form website’s allowlist. Server-side clients must send the same origin explicitly.
Example: https://customer-site.example

Request body

Customer-defined fields plus optional control fields. Turnstile is conditionally required. Nested objects and file uploads are not supported.

application/jsonapplication/x-www-form-urlencodedmultipart/form-data
Field Type Required Description
nameanyOptionalThe submitter’s name. Customer-defined; not required unless the form configures it.
Example: John Smith
emailanyOptionalThe submitter’s email address. Used as Reply-To when configured on the form.
phoneanyOptionalThe submitter’s phone number. Customer-defined.
Example: 0400000000
messageanyOptionalThe enquiry message. Customer-defined.
Example: I would like more information
cf-turnstile-responseanyOptionalCloudflare Turnstile token. Required only when Turnstile is enabled for the form.
Example: TURNSTILE_TOKEN
_honeypotanyOptionalOptional hidden honeypot field. It must be empty. A populated value returns a generic 403 response.
Example:
_idempotency_keyanyOptionalHTML-form alternative to the Idempotency-Key header. Maximum 128 characters and must match the header if both are supplied.
Example: 550e8400-e29b-41d4-a716-446655440000
Customer-defined fields are accepted through additionalProperties. Field names are not fixed by the API.

Code examples

Replace abc123 with the form’s public ID and send the customer website origin.

curl -X POST 'https://api.postvia.dev/v1/forms/abc123/submissions' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Origin: https://customer-site.example' \
  --data-raw '{"name":"John Smith","email":"[email protected]","phone":"0400000000","message":"I would like more information","cf-turnstile-response":"TURNSTILE_TOKEN"}'

Responses

Status Meaning Description
200ReplayIdempotent replay. The original submission is returned and no duplicate delivery or notification is created.
201CreatedSubmission accepted and durably stored. It is scheduled for delivery; email has not necessarily reached an inbox.
303RedirectNative HTML submission accepted. The browser is redirected to the form’s configured HTTPS success URL or the hosted thank-you page.
400Malformed requestThe request body was empty, malformed, or structurally unsupported.
403RejectedOrigin rejected, Turnstile verification failed, or the honeypot was filled. The response is generic and never echoes payload content.
404UnavailableThe form does not exist, is disabled, or a parent customer or website is disabled.
409ConflictThe same idempotency key was previously accepted with a different payload.
413Too largeThe request exceeded the 64 KiB body limit.
415UnsupportedThe content type or payload type is unsupported, including files and nested objects.
422ValidationOne or more submitted fields failed validation.
429Rate limitedA per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval.
500Internal errorAn unexpected server error occurred. No internal details are exposed.
503UnavailableThe form is not ready, CAPTCHA verification is temporarily unavailable, or the service cannot safely accept submissions.