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.
https://switchyard-ccn.modulify.website/api/in/{key}Stores the submission, answers right away, and then runs the live flows of the form.
Path
keystringrequired- The source key, shown with its full address in the form's Connect tab and on the Sources page.
Headers
Content-Typestringrequiredapplication/json,application/x-www-form-urlencodedormultipart/form-data.text/plainwith a JSON body works too.AuthorizationstringBearer <API key>. Optional. Skips the allowed websites check and the bot check.Idempotency-Keystring- Up to 200 characters. Sending the same key again within 24 hours returns the first submission instead of storing a new one.
Acceptstring- With
text/htmland a form post, you get a redirect or a thank you page. Everything else gets JSON.
Body
Send each answer under the key of its field. Values can be text, numbers or true and false, which are stored as text, or a list for fields that take several values. In a form post, repeat a name or end it with [] to send a list. In JSON, answers can also sit inside a data object.
Special fields
_redirectstring- Where to send the visitor after a classic form post. It wins over the redirect set on the form.
_gotchastring- The spam trap. Leave it empty. When it 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.
g-recaptcha-responsestring- The Google reCAPTCHA token, when the form uses reCAPTCHA.
These fields are read by the endpoint and never stored with the answers.
Limits
| What | Limit |
|---|---|
| Whole request | 25 MB |
| Answers without files | 64 KB in total, up to 200 fields, 10,000 characters per value, 100 values per list |
| Files | Up to 10 per submission, 10 MB each |
Examples
JSON
curl -X POST "https://switchyard-ccn.modulify.website/api/in/YOUR_SOURCE_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042" \
-d '{"email": "jane@example.com", "topic": "sales", "interests": ["speed", "support"], "rating": 5}'From your server, with an API key
const response = await fetch("https://switchyard-ccn.modulify.website/api/in/YOUR_SOURCE_KEY", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": `Bearer ${process.env.FORMERA_API_KEY}`
},
body: JSON.stringify({ full_name: "Jane Cooper", email: "jane@example.com", message: "Hello" })
})
const { ok, id, message } = await response.json()Files
curl -X POST "https://switchyard-ccn.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"Files are stored privately and open from the submission in your inbox. The answer of a file field is its file name.
Answer
JSON requests get the submission id and the form's success message:
{
"ok": true,
"id": "sub_7k2m9x4q1w3e5r6t",
"message": "Thanks, we've received your submission."
}A repeat with the same Idempotency-Key, or the same answers from the same source within 10 seconds, answers the same way with "duplicate": true and the first id. Classic form posts get a 303 redirect, or a thank you page when there is nowhere to go back to.
Errors carry "ok": false and a message:
{
"ok": false,
"message": "Submissions from example.org are not allowed for this form. Add the website under the form's allowed websites."
}Browsers and CORS
The endpoint answers OPTIONS preflights. Browsers may post from any of the form's allowed websites, or from anywhere when the form has none. It allows the Content-Type, Authorization, Idempotency-Key and X-Requested-With headers. A GET on the endpoint tells you which form it belongs to, which is handy to check an address.