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/submissionsHeaders and parameters
| Name | In | Required | Description |
|---|---|---|---|
| public_id | path | Required | Opaque public form identifier. Treat it as an identifier, not an authentication secret. Example: abc123 |
| Accept | header | Optional | Optional. Use application/json to receive a JSON response. Native HTML submissions receive a 303 redirect. Example: application/json |
| Idempotency-Key | header | Optional | Optional key for safe retries. Reuse the same key while the payload is unchanged. Maximum 128 characters. Example: 550e8400-e29b-41d4-a716-446655440000 |
| Origin | header | Required | Required. 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 |
|---|---|---|---|
| name | any | Optional | The submitter’s name. Customer-defined; not required unless the form configures it. Example: John Smith |
| any | Optional | The submitter’s email address. Used as Reply-To when configured on the form. Example: [email protected] | |
| phone | any | Optional | The submitter’s phone number. Customer-defined. Example: 0400000000 |
| message | any | Optional | The enquiry message. Customer-defined. Example: I would like more information |
| cf-turnstile-response | any | Optional | Cloudflare Turnstile token. Required only when Turnstile is enabled for the form. Example: TURNSTILE_TOKEN |
| _honeypot | any | Optional | Optional hidden honeypot field. It must be empty. A populated value returns a generic 403 response. Example: |
| _idempotency_key | any | Optional | HTML-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 |
|---|---|---|
| 200 | Replay | Idempotent replay. The original submission is returned and no duplicate delivery or notification is created. |
| 201 | Created | Submission accepted and durably stored. It is scheduled for delivery; email has not necessarily reached an inbox. |
| 303 | Redirect | Native HTML submission accepted. The browser is redirected to the form’s configured HTTPS success URL or the hosted thank-you page. |
| 400 | Malformed request | The request body was empty, malformed, or structurally unsupported. |
| 403 | Rejected | Origin rejected, Turnstile verification failed, or the honeypot was filled. The response is generic and never echoes payload content. |
| 404 | Unavailable | The form does not exist, is disabled, or a parent customer or website is disabled. |
| 409 | Conflict | The same idempotency key was previously accepted with a different payload. |
| 413 | Too large | The request exceeded the 64 KiB body limit. |
| 415 | Unsupported | The content type or payload type is unsupported, including files and nested objects. |
| 422 | Validation | One or more submitted fields failed validation. |
| 429 | Rate limited | A per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval. |
| 500 | Internal error | An unexpected server error occurred. No internal details are exposed. |
| 503 | Unavailable | The form is not ready, CAPTCHA verification is temporarily unavailable, or the service cannot safely accept submissions. |