Submit a form

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "EMAIL_FIELD_ID": "customer@example.com",
    "_gotcha": ""
  }'

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Accept: application/json" \
  --data-urlencode "EMAIL_FIELD_ID=customer@example.com" \
  --data-urlencode "_gotcha="

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Accept: text/html" \
  -H "Origin: https://your-website.example" \
  --data-urlencode "EMAIL_FIELD_ID=customer@example.com" \
  --data-urlencode "_gotcha=" \
  --data-urlencode "_redirect=https://your-website.example/thank-you"

{
  "ok": true,
  "submissionId": "SUBMISSION_ID",
  "title": "Thank you!",
  "message": "Your form has been submitted successfully."
}

{
  "ok": false,
  "code": "validation_error",
  "error": "Check the form fields and try again.",
  "fieldErrors": {
    "EMAIL_FIELD_ID": "Enter a valid value for Email."
  }
}

{
  "ok": true,
  "message": "Your form has been submitted successfully."
}

POST

api

forms

{formId}

submissions

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "EMAIL_FIELD_ID": "customer@example.com",
    "_gotcha": ""
  }'

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Accept: application/json" \
  --data-urlencode "EMAIL_FIELD_ID=customer@example.com" \
  --data-urlencode "_gotcha="

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Accept: text/html" \
  -H "Origin: https://your-website.example" \
  --data-urlencode "EMAIL_FIELD_ID=customer@example.com" \
  --data-urlencode "_gotcha=" \
  --data-urlencode "_redirect=https://your-website.example/thank-you"

{
  "ok": true,
  "submissionId": "SUBMISSION_ID",
  "title": "Thank you!",
  "message": "Your form has been submitted successfully."
}

{
  "ok": false,
  "code": "validation_error",
  "error": "Check the form fields and try again.",
  "fieldErrors": {
    "EMAIL_FIELD_ID": "Enter a valid value for Email."
  }
}

{
  "ok": true,
  "message": "Your form has been submitted successfully."
}

Submit answers using the form’s saved field IDs. This is a public endpoint: no tenant API key or staff session is required. Include _password if the form is password-protected. Follow Build a headless form to copy your endpoint, field IDs, consent text, and optional JavaScript from Share.

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "EMAIL_FIELD_ID": "customer@example.com",
    "_gotcha": ""
  }'

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Accept: application/json" \
  --data-urlencode "EMAIL_FIELD_ID=customer@example.com" \
  --data-urlencode "_gotcha="

curl -X POST "https://app.nautilus.co/api/forms/FORM_ID/submissions" \
  -H "Accept: text/html" \
  -H "Origin: https://your-website.example" \
  --data-urlencode "EMAIL_FIELD_ID=customer@example.com" \
  --data-urlencode "_gotcha=" \
  --data-urlencode "_redirect=https://your-website.example/thank-you"

{
  "ok": true,
  "submissionId": "SUBMISSION_ID",
  "title": "Thank you!",
  "message": "Your form has been submitted successfully."
}

{
  "ok": false,
  "code": "validation_error",
  "error": "Check the form fields and try again.",
  "fieldErrors": {
    "EMAIL_FIELD_ID": "Enter a valid value for Email."
  }
}

{
  "ok": true,
  "message": "Your form has been submitted successfully."
}

Request rules

Send a flat JSON object, URL-encoded form data, or text-only multipart data. Do not nest answers inside data.
Replace example field names with the exact saved IDs. Required fields and available choices depend on the form.
Include _gotcha and leave it empty. A filled trap receives an acknowledgment without creating a submission or triggering side effects.
Keep the complete body at or below 65,536 bytes. Files are not supported.
Supply _redirect only when its destination has the same origin as the request’s Origin header.

JSON requests always receive JSON. Native requests that accept HTML receive an HTML confirmation or a 303 redirect. JSON confirmations include redirectUrl when supplied and validated.

Public access

The route accepts cross-origin submissions. OPTIONS returns 204 with Access-Control-Allow-Origin: *, allowed methods POST, OPTIONS, and allowed headers Content-Type, Accept. The published form ID grants submission access only. Reading configuration or saved submissions through /api/v1/forms still requires a tenant API key. A 401 from this submission endpoint means the form password is missing or incorrect; adding an API key does not replace that password.

Confirmation and availability

Only a saved submission includes submissionId. The receipt confirms persistence, not completion of every notification or automation. Notifications are scheduled after the response, so a slow email provider does not delay confirmation. Do not automatically retry an uncertain request because no request idempotency key is supported. Email verification, POS enrollment, file-upload fields, and unsupported saved field definitions return 409 hosted_form_required. Null optional field settings are treated as omitted; malformed definitions and comparison rules remain unsupported. Use the hosted flow when the sharing panel indicates it is required. See the guide for answer formats, tracking limits, and spam protection.

Headers

Origin

string

Submitting website origin. Required when _redirect is supplied; the redirect destination must match its scheme, host, and port.

Path Parameters

formId

string

required

Published form ID copied from Share. It permits submission only.

Required string length: 1 - 200

Pattern: ^[a-zA-Z0-9_-]+$

Body

Flat saved field IDs and control fields. Include every required visible answer. For multipart, let the browser generate the Content-Type boundary; files are not supported. HTML checkbox groups use repeated field names.

Flat answers keyed by the published form's saved field IDs, plus the controls below. There is no data wrapper. Only IDs belonging to that form are accepted; requiredness, choices, and conditional visibility come from its saved definition. Total body size is limited to 65536 bytes, including multipart overhead.

_gotcha

string

default:""

required

Required hidden bot-trap field. Leave it empty for real submissions. A nonempty value receives an acknowledgment without a submissionId and creates no records or downstream effects.

Maximum string length: 10000

_password

string<password>

The form password, required only when the published form is password-protected. This is not a tenant API key.

Maximum string length: 1024

_redirect

string

Optional thank-you URL, either relative to Origin or an absolute HTTP(S) URL with the same scheme, host, and port. Requires the Origin header. Native HTML receives a 303 redirect; JSON receives redirectUrl.

Maximum string length: 2000

_utm_source

string

Optional utm_source attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_utm_medium

string

Optional utm_medium attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_utm_campaign

string

Optional utm_campaign attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_utm_term

string

Optional utm_term attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_utm_content

string

Optional utm_content attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_gclid

string

Optional gclid attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_gbraid

string

Optional gbraid attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_wbraid

string

Optional wbraid attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_fbclid

string

Optional fbclid attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_referrer

string

Optional referrer attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

_landing_url

string

Optional landing_url attribution. Strings are trimmed to 450 characters when stored. Empty or malformed values are ignored without rejecting valid answers; the complete request must still fit within 65536 bytes.

{key}

Answer to a saved field ID. Strings cover text, email, phone, numeric text, dates, and choices; arrays represent multiple checkbox choices. Null is treated as an empty answer and remains subject to required-field validation. Nested objects and uploaded files are rejected.

Maximum string length: 10000

Response

Saved-submission receipt, or ordinary acknowledgment for a filled honeypot. Only a saved submission includes submissionId.

Acknowledgment of a saved submission or a filled honeypot. Only a saved submission has submissionId. The receipt does not include answers, contact records, or notification recipients and does not guarantee completed downstream delivery.

boolean

required

message

string

required

Configured success message or ordinary honeypot acknowledgment.

submissionId

string

Identifier of the saved submission. Absent for a filled honeypot.

title

string

Configured success title, returned for a saved submission.

redirectUrl

string<uri>

Validated absolute thank-you URL, when requested. The JSON client decides when to navigate.

API documentation

Sites

Products

Checkout links

Purchases

Contacts

Marketing

Forms

Vouchers

Links

Automations

Surveys

Cases

Reviews

Cancellations

POS

Message

Email

Analytics

Integration

Request rules

Public access

Confirmation and availability

Headers

Path Parameters

Body

Response

​Request rules

​Public access

​Confirmation and availability

Headers

Path Parameters

Body

Response

Request rules

Public access

Confirmation and availability