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-idThe 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 |
|---|---|
| Accepts a submission. |
| Returns |
| Returns a small page explaining that the URL accepts form submissions via POST. Nothing is stored. |
Content types
| How the body is read |
|---|---|
| A standard HTML form post. |
| Text fields and files. Required for file uploads. |
| 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 ascolors[], 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 |
|---|---|
| Honeypot. If it has a value, the submission is discarded and the normal success response is returned. Never stored. |
| Subject of the notification email for this submission. |
| Reply-To address of the notification email. Takes priority over a field named |
| 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. |
| Solution from the built-in captcha widget. |
| Captcha token when the form uses reCAPTCHA v2 or v3. Removed before storing. |
| Captcha token when the form uses hCaptcha. Removed before storing. |
| 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
emailthat contains an email address is used as the Reply-To address of the notification email, unless_replytois 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 |
|
Browser | The form has a redirect URL, or the submission has a valid |
|
Browser | No redirect URL |
|
JSON body:
{ "ok": true, "id": "V1StGXR8_Z5jdHi6B-myT" }idis the 21-character submission ID.idisnullwhen 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 |
| This form does not exist. | The form ID in the URL is wrong, or the form was deleted. |
403 |
| This form is not accepting submissions. | The form is paused in its settings. |
403 |
| Submissions from this website are not allowed. | The form has allowed domains and the request came from a different website. |
403 |
| Submission blocked. | The sender's IP address is on the form's block list. |
413 |
| Submission is too large. | The request is larger than 50 MB. |
413 |
| Names the file and the plan's per-file limit. | A file is larger than the workspace plan's per-file limit. |
400 |
| Could not read the submission body. | The body could not be parsed. |
400 |
| Varies, for example "reCAPTCHA v2 token is missing". | The captcha token was missing, invalid, or scored too low. |
402 |
| 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 |
| The first field error, plus a count of the others. | One or more builder fields failed validation. |
429 |
| 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 |
| This form's file storage is full. | The uploaded files do not fit in the workspace's storage. |
500 |
| Could not store the uploaded files. Please try again. | A temporary problem while saving files. |
500 |
| 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: OriginOnly 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
- JavaScript and AJAX: handle these responses in the browser.
- Validation rules: what triggers a 422.
- Data retention: how the monthly quota works.
Ready to try it? Create a free account and send your first submission.