Submission API reference

Endpoint

POST https://api.surveyowl.co/v1/submit/YOUR_FORM_PUBLIC_KEY

The endpoint accepts requests from browser forms, frontend applications, and servers. Replace YOUR_FORM_PUBLIC_KEY with the Public Key from the Endpoint form’s General tab.

Form-specific URL

The Public Key is the final URL segment. The request body contains only the answers you want to collect:

{
  "name": "Ada Lovelace",
  "email": "[email protected]"
}

No hidden authentication field or Authorization header is required. If you turned on domain restriction, the request also has to come from one of your allowed domains.

Accepted request formats

Content type	Use it for
`application/json`	JavaScript applications and server requests
`application/x-www-form-urlencoded`	Normal HTML forms without files
`multipart/form-data`	Forms with one or more file uploads

The JSON or URL-encoded body is limited to 1 MB. File limits and storage allowances depend on the form owner’s plan.

Answer fields

Every field other than the reserved request fields becomes part of the stored response. Use short, stable names that are clear in the dashboard and exports:

{
  "full_name": "Ada Lovelace",
  "email": "[email protected]",
  "topic": "Product demo",
  "message": "Please contact me next week."
}

For an HTML form, the input’s name becomes the answer name. An input without a name is not submitted.

Reserved fields

Field	Purpose	Stored as an answer?
`redirect`	Sends a plain HTML submission to an `http://` or `https://` URL after success	No
CAPTCHA token field	Verifies the challenge configured in Settings	No

The CAPTCHA field is g-recaptcha-response, h-captcha-response, or cf-turnstile-response, depending on the provider.

Success response

A successful JSON or JavaScript request returns an acknowledgement:

{
  "message": "Thank you! Your response has been recorded."
}

The usual success status is 201 Created. The endpoint may return 202 Accepted when the response has been safely queued for background processing. Treat any 2xx status as success. When the response is queued, the message reads “Thank you! Your response has been received and is being processed.” instead. The response does not expose the stored answers, submission ID, or timestamp. The form owner can view those details under Submissions.

Domain restriction

An Endpoint form can be limited to your own websites. Open the form’s Settings, turn on Domain restriction, and add up to five domains. Subdomains of a listed domain are allowed automatically, so example.com also covers www.example.com. Use Allow localhost while you develop. The check reads the request’s Origin or Referer header. Browsers send one of them; a plain server-to-server call usually does not, so it is rejected while the restriction is on. Rejected requests get a 403 with the code domain_not_allowed.

Error response

Errors use one of these shapes:

{
  "success": false,
  "data": null,
  "error": "invalid Public Key"
}

{
  "success": false,
  "data": null,
  "error": {
    "code": "captcha_required",
    "message": "captcha verification is required for this form"
  }
}

Always check the HTTP status or response.ok before showing a success message. See Troubleshooting for common causes.

Welcome

Hosted forms

Endpoint forms

Responses

Integrations

Build your form

Publish and share

Settings

Payments

Account and billing

Submission API reference

Endpoint

Form-specific URL

Accepted request formats

Answer fields

Reserved fields

Success response

Domain restriction

Error response

​Endpoint

​Form-specific URL

​Accepted request formats

​Answer fields

​Reserved fields

​Success response

​Domain restriction

​Error response

Endpoint

Form-specific URL

Accepted request formats

Answer fields

Reserved fields

Success response

Domain restriction

Error response