A form backend for developers: one endpoint for JSON, form posts and files
Post JSON, form posts or files to one endpoint, get errors per field back, and retry safely with an Idempotency-Key.
2 min read
On this page
Every form on a site needs the same boring backend: accept the post, check the answers, store them, keep spam out, tell someone, and never lose a submission when the network blinks. Writing that once is fine. Writing it for the fifth landing page is not. Formpik gives every form one endpoint that does all of it, and you call it like any other API.
One endpoint, three kinds of body
Each source in Formpik has its own address. Post to it from a browser, a server or a script:
curl -X POST https://formpik.com/api/in/{source_key} \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Idempotency-Key: signup-1042" \
-d '{ "name": "Ada Lovelace", "email": "ada@example.com", "message": "Hello" }'The same address takes JSON, a classic form post, and multipart uploads with up to 10 files of 10 MB each and 25 MB per request. Uploaded files are stored privately, and the dashboard and the API hand them out through links that expire after 15 minutes.
What comes back
A request that asks for JSON gets an answer it can act on:
{ "ok": true, "id": "sub_8f2k4m", "message": "Thanks, we got your message." }The message is the form's own success message, and when the form sends visitors somewhere after submitting, a redirect comes with it. A classic form post without JavaScript gets a redirect instead, either to your thank you page or back to the page it came from.
Errors you can show next to each field
Turn on Refuse answers that break the field rules for the form, and a submission that breaks one is refused with a 422 and nothing is stored. The answer carries one message per field, keyed by the field key and written for visitors:
{
"ok": false,
"message": "Please check the highlighted fields.",
"reason": "Email: Use your work email address",
"errors": { "email": "Use your work email address" }
}To check a field while someone is still typing, post the answers to /api/in/{source_key}/validate. It runs the same rules, stores nothing, and answers { "ok": true, "valid": false, "errors": { ... } }.
Retry without duplicates
Networks fail at the worst moment. Send an Idempotency-Key header with each submission, and a retry with the same key answers the first submission's id instead of storing it twice. Exact repeats inside 10 seconds are dropped even without a key, which also covers the visitor who clicks the button twice.
Limits that protect you
- 120 posts a minute per address across every form, answered with a
429above that. - The form's own limit per visitor per hour, and your plan's monthly submissions.
- Allowed websites, so browsers can only post from your domains. A server that posts with
Authorization: Bearer <API key>skips that check.
Then everything else happens
The endpoint answers first and works after. Each stored submission runs through the form's flows, which can check it, ask AI to read it, and deliver it to email, Slack, Teams, Discord or a signed webhook. When you would rather pull than be pushed, the REST API under /api/v1 lists and reads submissions with the same API key.
The submitting guide covers every option, and errors lists each status and what to do about it.