> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surveyowl.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Submission API reference

> Endpoint format, request formats, reserved fields, and API responses.

## Endpoint

```text theme={null}
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:

```json theme={null}
{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}
```

No hidden authentication field or Authorization header is required. If you turned on [domain restriction](#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:

```json theme={null}
{
  "full_name": "Ada Lovelace",
  "email": "ada@example.com",
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "success": false,
  "data": null,
  "error": "invalid Public Key"
}
```

```json theme={null}
{
  "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](/developer-api/troubleshooting) for common causes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.