How it works
Follow a submission through FormDB step by step: the checks it passes, what each failure does, and what happens once it is stored.
This page explains what FormDB does with a submission, in the exact order it happens. Knowing the order helps you understand why a submission was rejected, flagged as spam or never showed up.
The short version
Your form sends its data to an endpoint, which is a web address unique to your form: https://api.formdb.io/f/your-form-id. FormDB runs a series of checks. If every check passes, the submission is stored in the form's inbox, a notification email is sent, and any integrations you connected receive a copy. The visitor then sees a thank-you page, your own redirect page, or a JSON response.
No API key or login is needed to submit. The form ID in the URL is the only identifier.
The checks, in order
FormDB stops at the first check that fails. Nothing after it runs.
- The form exists. An unknown form ID returns
404 form_not_found. - The form is accepting submissions. A paused form returns
403 form_inactive. - Allowed domains. If you listed allowed domains and the request comes from a website that is not on the list, it returns
403 origin_not_allowed. See Blocking and allowed domains. - Blocked IPs. If the visitor's IP address is on the form's block list, it returns
403 blocked. - Size. A request larger than 50 MB returns
413 too_large. Files uploaded straight to storage with FormDB's helper script do not count toward this. See File uploads. - Reading the body. If FormDB cannot read the data, it returns
400 invalid_body. - Honeypot. If the hidden
_gotchafield has a value, FormDB pretends everything worked and throws the submission away. Nothing is stored. - Captcha. If you set up a captcha and the token is missing or invalid, it returns
400 captcha_failed. See Captcha. - File uploads allowed. If the submission contains files and the workspace's plan does not include file uploads, it returns
402 uploads_disabled. Every current plan, including Free, includes file uploads. - Validation. Fields you defined in the form builder are checked against their rules. A failure returns
422 validation_failed. See Validation rules. - Spam filter. If the spam filter is on, the content is scanned. This step never rejects anything. It only decides whether the submission goes to the Inbox or the Spam folder.
- Monthly quota. If the workspace has used all of its submissions for the period, the submission is held: it is stored, but its notifications and integrations wait until it is released. Once one extra period's worth has been held, it returns
429 limit_reached. Spam does not count toward the quota and skips this check. - File storage. Uploaded files are saved. If they would not fit in the workspace's storage, it returns
413 storage_full. - Saving. The submission is stored.
- Notifications and integrations. The notification email, any auto-reply and your enabled integrations are queued. They run in the background after the visitor already has a response. On paid plans, they run after uploaded files have been scanned for viruses.
What the three kinds of failure do
Rejected submissions (every numbered error code above) are not stored anywhere. The visitor sees an error, and you cannot recover the data later. This includes submissions that arrive after your monthly quota and the extra held allowance are both used up.
Held submissions arrive after the monthly quota is used up. They are stored and the sender sees the normal success response. Notifications and integrations run when they are released, after an upgrade or when the quota resets. See Data retention.
Honeypot hits are dropped silently. The bot receives the normal success response, so it has no reason to try again in a different way. They do not count toward your quota.
Spam-flagged submissions are stored, but only in the form's Spam folder. They do not count toward your quota, do not send a notification email, do not reach your integrations, and any files attached to them are discarded. The sender sees the normal success response. If the filter made a mistake, you can move the submission to the Inbox with Not spam.
What the visitor sees
FormDB decides how to respond based on how the form was sent.
- A plain HTML form (a normal browser post): the visitor is sent to your redirect URL if you set one. Otherwise they see FormDB's hosted thank-you page. Errors are shown on a hosted page titled "Submission failed".
- JavaScript that sends the header
Accept: application/json, or sends JSON: FormDB answers with JSON and never redirects. Success is201with{"ok": true, "id": "..."}.
See HTML forms and JavaScript and AJAX for both approaches.
What is stored with each submission
Along with the field values and files, FormDB records the visitor's IP address, approximate location (country, region, city), browser user agent, and the page the form was submitted from. You can see these in the submission's Details section in the inbox.
After it is stored
- The submission appears in the form's Submissions tab as unread.
- The workspace owner, plus any extra recipients you added, receive an email. See Email notifications.
- Enabled webhooks, chat notifications and, on paid plans, other integrations receive the submission. Failed deliveries are retried automatically. See Webhooks.
- On paid plans, an auto-reply is sent to the submitter if the form has one set up.
Next steps
- Endpoint reference: every status code and response body.
- Spam protection: how the spam layers fit together.
- Data retention: quotas, resets and how long submissions are kept.
Ready to try it? Create a free account and send your first submission.