API reference
Send a submission
Every source has an endpoint that takes submissions as JSON, as a regular form post, or as a multipart upload with files. It stores the submission, answers right away, and then runs the live flows of the form.
On this page you will learn
- The endpoint, its headers and its body
- Examples in cURL, JavaScript, Python and HTML
- How to upload files
- What it answers, for JSON and for classic form posts, including where the visitor goes next
- How duplicates and Idempotency-Key work
- CORS and the order of every check
https://formpik.modulify.website/api/in/{key}Stores the submission, answers right away, and then runs the live flows of the form.
https://formpik.modulify.website/api/in/{key}Answers browser preflights: 204 for an allowed website, 403 otherwise.
https://formpik.modulify.website/api/in/{key}Says which form the endpoint belongs to. Handy to check an address, it stores nothing.
https://formpik.modulify.website/api/in/{key}/validateChecks answers against the field rules and stores nothing, for websites that show what to fix before sending.
https://formpik.modulify.website/api/in/{key}/rulesLists the fields of the form with their types, options and rules.
Path
keystringrequired- The source key: 6 to 64 lowercase letters and digits. It is part of the source's
endpoint_url, shown in the form's Connect tab, on the Sources page and by GET /api/v1/sources. A key in capitals is read in lowercase.
Headers
Content-Typestringrequiredapplication/json,application/x-www-form-urlencodedormultipart/form-data.text/plainwith a JSON body works too. Anything else gets a415.AuthorizationstringBearer <API key>. Optional. With any key of the form's workspace, read only or full access, the allowed websites check and the bot check are skipped. A wrong key gets a401instead of being ignored.Idempotency-Keystring- Any text up to 200 characters, such as order-1042. Sending the same key to the same source again within 24 hours returns the first submission instead of storing a new one.
Acceptstring- A request that asks for
text/htmlwithout sending JSON is treated as a classic form post and gets a redirect or a page. Everything else gets JSON. X-Requested-Withstring- Any value. Forces a JSON answer, also for a form post or an upload.
Body
Send each answer under the key of its field. Read the keys from the Connect tab or from the fields of GET /api/v1/forms/{id}.
- Text is stored as it is. Numbers and true or false are stored as text, so
5becomes"5". - Lists are stored as lists, for fields that take several values. In a form post, repeat a name or end it with
[]:interests[]=speed&interests[]=support. The[]is dropped from the stored key. - In JSON, the answers can also sit inside a
dataobject:{"data": {"email": "jane@example.com"}}. - Nested objects are stored as JSON text.
nullvalues are left out. - Answers with names the form does not know are still stored. With Learn new fields automatically on, they are added to the form as fields, up to 50 per submission.
- The endpoint does not check required fields or option values. A Validate step in a flow does, and can send incomplete submissions down another path.
Special fields
_redirectstring- Where to send the visitor afterwards, as a full
https://orhttp://address. See Where the visitor goes next. _gotchastring- The spam trap. Leave it empty. When the form has its spam trap on and this has a value, the submission is stored as spam and no flows run.
cf-turnstile-responsestring- The Cloudflare Turnstile token, when the form uses Turnstile as its bot check.
g-recaptcha-responsestring- The Google reCAPTCHA token, when the form uses reCAPTCHA as its bot check.
These fields, and h-captcha-response, are read by the endpoint and never stored with the answers.
Limits
| What | Limit | Above it |
|---|---|---|
| Whole request | 25 MB | 413 |
| Answers without files | 64 KB in total | 413 |
| Fields | 200 per submission | Further names are dropped |
| One value | 10,000 characters | Cut to the limit |
| One list | 100 values | Cut to the limit |
| Field name | 100 characters | Cut to the limit |
| Files | 10 per submission, 10 MB each | 413 |
Examples
curl -X POST "https://formpik.modulify.website/api/in/YOUR_SOURCE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{"full_name": "Jane Cooper", "email": "jane@example.com", "topic": "sales", "interests": ["speed", "support"]}'On a website you do not have to write the fetch yourself: the Formpik site script catches the form, posts it and shows the message or goes on to the next page. See After submitting.
Files
Send files as a multipart/form-data upload. Each file goes under the key of its file field, with [] when the field takes several.
curl -X POST "https://formpik.modulify.website/api/in/YOUR_SOURCE_KEY" \
-F "email=jane@example.com" \
-F "brief=@brief.pdf" \
-F "photos[]=@roof-front.jpg" \
-F "photos[]=@roof-back.jpg"- Up to 10 files, 10 MB each, within the 25 MB request limit. An 11th file or a larger file refuses the whole submission with a 413 that names the file.
- Empty file inputs are ignored.
- The answer of a file field is its file name, or a list of names. File names are kept up to 120 characters.
- Files are stored privately. The API lists them under
filesof one submission, and GET .../files/{fileId} answers with a link that works for 15 minutes.
Answer
JSON requests
A stored submission answers 200 with its id and the form's success message:
{
"ok": true,
"id": "sub_7k2m9x4q1w3e",
"message": "Thanks, we've received your submission."
}okbooleanrequiredtruewhen the submission was stored, or was a repeat of one that was.idstring- The submission id. Read it with GET /api/v1/submissions/{id}.
duplicateboolean- Only present, and
true, when this request was a repeat.idis then the first submission. messagestringrequired- The form's success message, or on an error what went wrong. Written for people, so you can show it as it is.
redirectstring- Only present when this submission should go on to a page. See Where the visitor goes next.
redirectDelaynumber- With
redirect: the seconds to showmessagebefore going on,0,3or5. redirectRuleboolean- With
redirect:truewhen a Pages by answer rule picked the page. Such a page should win over a redirect the website sets itself.
{
"ok": true,
"id": "sub_7k2m9x4q1w3e",
"message": "Thanks, we've received your submission.",
"redirect": "https://yourcompany.com/thanks?name=Jane",
"redirectDelay": 3,
"redirectRule": false
}Errors carry "ok": false, a message and a reason:
{
"ok": false,
"message": "Sorry, something went wrong. Please email us at hello@yourcompany.com.",
"reason": "Submissions from example.org are not allowed for this form. Add the website under the form's allowed websites."
}reason always says exactly what went wrong, so log it. message is the form's own Error message when it has one, and the same text as reason otherwise, so you can show it to visitors as it is.
Answers that break a field rule
When the form has Refuse answers that break the field rules on, a submission that breaks one is refused with a 422 and nothing is stored. errors holds one message per field, keyed by the field key, written for visitors:
{
"ok": false,
"message": "Please check the highlighted answers and try again.",
"reason": "Email: Use your work email address. Country: Choose one of the listed countries",
"errors": {
"email": "Use your work email address",
"country": "Choose one of the listed countries"
}
}With the setting off, the submission is stored anyway and its broken rules are kept as meta.rule_errors, where a Validate step or your own code can act on them. See Field rules for every rule.
A 200 means the submission is stored, not that it was delivered: the flows run after the answer. Read the submission later, or use a webhook, to see the result. Spam is also answered with 200, so bots learn nothing.
Classic form posts
A form post from a browser that asks for HTML gets a page or a redirect instead of JSON:
- When there is a page to go to and the form shows its message first, a
200Thank you page with the success message that goes on afterredirectDelayseconds. - When there is a page to go to right away, a
303redirect there, so a reload never posts twice. - Otherwise a
303back to the page the form was on (theReferer) with?submitted=1added. - When there is no such page either, a
200Thank you page with the success message.
Refused classic posts get a short Not sent page with the message and the error status.
Where the visitor goes next
The page in redirect is the first of these that gives a valid address:
- The first Pages by answer rule of the form that matches the answers.
redirectRuleis thentrue. - The
_redirectfield sent with the submission. - The form's own page, when its settings say Go to a page after submitting.
- Addresses set in the form can carry answers, such as
https://yourcompany.com/thanks?name={{full_name}}. Each answer is URL encoded and can only come after the website address, so a visitor can change what the page shows but never which website they go to.{{submission.id}}and{{form.name}}work too. - Placeholders in
_redirectare removed, since the page itself sent it. - With none of the three, there is no
redirectand the visitor stays on the page with the message.
The settings behind this are after_submit, redirect_url, redirect_rules, redirect_delay, success_message and error_message, which you can change with PATCH /api/v1/forms/{id}.
Check answers without storing
POST /api/in/{key}/validate takes the same bodies, headers and allowed websites as the endpoint, runs the same field rules, and stores nothing. It answers 200 whether the answers pass or not, so a website can check one field as the visitor leaves it, or a whole step of a multi-step form.
{
"ok": true,
"valid": false,
"errors": {
"email": "Use your work email address"
},
"message": "Please check the highlighted answers and try again.",
"reason": "Email: Use your work email address"
}validbooleanrequiredtruewhen every answer passes. Fields you did not send count as empty, so required ones show up inerrors: read only the ones you checked.errorsobjectrequired- One message per field key. Empty when everything passes.
message, reasonstring- Only when something fails, the same as in the
422of the endpoint.
It allows 300 checks a minute per address. One per answer and Blocked words stay on the server: one per answer is checked only on a real send, so this address never reveals who already signed up, and blocked words are checked but never listed.
GET /api/in/{key}/rules answers the fields that collect answers, each with key, label, type, required, multiple, options for choice fields (a Country field lists only the countries its rule keeps), accept for files, and rules in the same snake_case names as the API. It is cached for a minute and needs no key.
Duplicates and retries
- Same answers within 10 seconds. When the same source gets exactly the same answers again within 10 seconds, nothing new is stored. This catches double clicks and impatient retries.
- Idempotency-Key. When you send a key, a repeat with the same key to the same source within 24 hours answers with the first submission, even if the answers changed. Use one key per thing you send, such as
order-1042. - A repeat answers like the original, with the first id and
"duplicate": truein JSON, or the same kind of redirect for a classic post. It runs no flows and does not count toward your monthly submissions. - Both checks are kept in the memory of the endpoint server, so treat them as protection against quick retries. After a restart a repeat can be stored again, so key your own records on the submission id when it matters.
- On a
500or a network error, it is safe to send again with the sameIdempotency-Key.
{
"ok": true,
"id": "sub_7k2m9x4q1w3e",
"duplicate": true,
"message": "Thanks, we've received your submission."
}Browsers and CORS
- The endpoint answers
OPTIONSpreflights with204for allowed websites and lets the browser keep that answer for a day. - Browsers may post from any of the form's allowed websites or their subdomains, or from anywhere when the form has none.
- A preflight from another website gets a
403without CORS headers, so the browser stops a JSON request there. A plain form post needs no preflight: it gets the403answer with CORS headers, so the page can read why and show it. - Allowed request headers:
Content-Type,Authorization,Idempotency-KeyandX-Requested-With. - Requests without an
OriginorReferer, such as server calls, are never blocked by allowed websites.
Order of checks
The endpoint checks every request in this order and stops at the first problem, so the error you get is the first one that applies:
- 01Key and accessSource key (404), method (405), API key (401), allowed website (403), paused source or form (403).
- 02Rate and body120 a minute per address (429), body type (415), size (413), empty or broken body (400).
- 03Repeats, rules and limitsRepeats answer the first id. Then the field rules when the form refuses broken answers (422), monthly submissions and the hourly limit per visitor (429).
- 04Store and runSpam checks, store with files, answer, then run the live flows.
Common questions
Do I need the API key in a web page?
Which API key should my server use to send?
Why do I get 200 but the submission shows Needs attention?
Can I send booleans and numbers?
true becomes "true" and 5 becomes "5". For yes or no fields, send yes or no.