Endpoint reference

Reference for the FormDB submission endpoint: URL, methods, content types, reserved fields, success responses, error codes and size limits.

This page is the precise reference for the submission endpoint: what you can send, what comes back, and every error code. For a guided introduction, start with the Quickstart.

URL

https://api.formdb.io/f/your-form-id

The form ID is 10 characters long and uses lowercase letters and digits. You can copy the full endpoint from the top of any form page in the dashboard.

No authentication is needed to submit. There is no API key or token. The form ID is the only identifier.

Methods

Method

Behaviour

POST

Accepts a submission.

OPTIONS

Returns 204 with CORS headers. Browsers send this automatically before some cross-site requests.

GET

Returns a small page explaining that the URL accepts form submissions via POST. Nothing is stored.

Content types

Content-Type

How the body is read

application/x-www-form-urlencoded

A standard HTML form post.

multipart/form-data

Text fields and files. Required for file uploads.

application/json

The body must be a JSON object. Nested objects and arrays are stored as they are. Files are not possible.

Anything else, or missing

The body is read as URL-encoded key and value pairs.

Notes on parsing:

  • A field name that appears several times is stored as a list of values.
  • A field name ending in [], such as colors[], is always stored as a list, and the [] is removed from the name.
  • Empty file inputs are ignored.
  • Invalid JSON, or JSON that is an array or a plain value, is treated as an empty submission. No parse error is returned, but required fields will then fail validation.

Reserved and special fields

Field

Meaning

_gotcha

Honeypot. If it has a value, the submission is discarded and the normal success response is returned. Never stored.

_subject

Subject of the notification email for this submission.

_replyto

Reply-To address of the notification email. Takes priority over a field named email.

_next

Where to redirect the browser after a successful plain HTML form post. It must be on the submitting site or one of the form's allowed domains, otherwise it is ignored.

altcha

Solution from the built-in captcha widget.

g-recaptcha-response

Captcha token when the form uses reCAPTCHA v2 or v3. Removed before storing.

h-captcha-response

Captcha token when the form uses hCaptcha. Removed before storing.

cf-turnstile-response

Captcha token when the form uses Cloudflare Turnstile. Removed before storing.

A captcha token field is only removed when that provider is the one selected on the form. There is no _cc field.

Two naming conventions have an effect without being reserved:

  • A field named email that contains an email address is used as the Reply-To address of the notification email, unless _replyto is sent.
  • Fields whose names start with _ are stored, but left out of the notification email.

Recipients cannot be set from inside the form. They are configured in the dashboard.

JSON mode and browser mode

FormDB replies with JSON when the request's Accept header contains application/json, or when its Content-Type contains application/json. Every other request is treated as a browser form post and receives a web page or a redirect.

Success responses

Mode

Condition

Response

JSON

Always

201 with a JSON body. The redirect URL is ignored.

Browser

The form has a redirect URL, or the submission has a valid _next

303 redirect to that URL. _next takes priority.

Browser

No redirect URL

200 with the hosted thank-you page.

JSON body:

{ "ok": true, "id": "V1StGXR8_Z5jdHi6B-myT" }
  • id is the 21-character submission ID.
  • id is null when the honeypot discarded the submission.
  • Submissions flagged as spam receive the same success response, with a real id.

Error responses

In JSON mode, every error has this shape:

{
  "ok": false,
  "error": {
    "code": "form_inactive",
    "message": "This form is not accepting submissions."
  }
}

In browser mode, the same HTTP status is returned with a hosted page titled "Submission failed" that shows the message.

Error codes

Status

Code

Message

Meaning

404

form_not_found

This form does not exist.

The form ID in the URL is wrong, or the form was deleted.

403

form_inactive

This form is not accepting submissions.

The form is paused in its settings.

403

origin_not_allowed

Submissions from this website are not allowed.

The form has allowed domains and the request came from a different website.

403

blocked

Submission blocked.

The sender's IP address is on the form's block list.

413

too_large

Submission is too large.

The request is larger than 50 MB.

413

file_too_large

Names the file and the plan's per-file limit.

A file is larger than the workspace plan's per-file limit.

400

invalid_body

Could not read the submission body.

The body could not be parsed.

400

captcha_failed

Varies, for example "reCAPTCHA v2 token is missing".

The captcha token was missing, invalid, or scored too low.

402

uploads_disabled

File uploads are not available on this form's plan.

The submission contains files and the workspace's plan does not include file uploads.

422

validation_failed

The first field error, plus a count of the others.

One or more builder fields failed validation.

429

limit_reached

This form has reached its monthly submission limit.

The workspace has used its monthly quota and the extra held allowance. Before that, over-quota submissions are held and get a success response.

413

storage_full

This form's file storage is full.

The uploaded files do not fit in the workspace's storage.

500

upload_failed

Could not store the uploaded files. Please try again.

A temporary problem while saving files.

500

server_error

Something went wrong. Please try again.

A temporary problem while saving the submission.

Rejected submissions are not stored.

Extra detail on two errors

validation_failed adds a fields object keyed by field name, with one error per field:

{
  "ok": false,
  "error": {
    "code": "validation_failed",
    "message": "Email must be a valid email address. (+1 more)",
    "fields": {
      "email": { "message": "Email must be a valid email address.", "rule": "type" },
      "message": { "message": "Message is required.", "rule": "required" }
    }
  }
}

See Validation rules for the possible rule values.

limit_reached adds limit, the plan's monthly number:

{
  "ok": false,
  "error": {
    "code": "limit_reached",
    "message": "This form has reached its monthly submission limit.",
    "limit": 250
  }
}

Order of checks

Checks run in this order, and the first failure is the one returned: form exists, form is active, allowed domains, blocked IPs, request size, body parsing, honeypot, captcha, uploads allowed on the plan, validation, spam filter, monthly quota, file storage, saving. See How it works for a description of each step.

CORS headers

Sent on OPTIONS and on every POST response except the 303 redirect:

Access-Control-Allow-Origin: <the request's Origin, or * when there is none>
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Accept
Access-Control-Max-Age: 86400
Vary: Origin

Only the Content-Type and Accept request headers are allowed. Access-Control-Allow-Credentials is not sent.

Limits

Limit

Value

Request size

50 MB per submission, all fields and files together. Files uploaded straight to storage with the helper script do not count.

Size per file

10 MB on Free, 25 MB on Starter, 100 MB on Growth, 250 MB on Business. Set a lower one per field with a Max file size rule.

Number of files

No fixed limit. Set one per field with Min files and Max files rules.

File types

No fixed list. Set one per field with an Allowed types rule.

Submissions per month

Depends on the workspace's plan. See Plans and billing.

File storage

Depends on the workspace's plan.

A quick test with curl

curl -X POST https://api.formdb.io/f/your-form-id \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email":"jane@example.com","message":"Hello from curl"}'

Next steps

Ready to try it? Create a free account and send your first submission.