Skip to content

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.

POSThttps://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-Typestringrequired
application/json, application/x-www-form-urlencoded or multipart/form-data. text/plain with a JSON body works too.
Authorizationstring
Bearer <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/html and 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

WhatLimit
Whole request25 MB
Answers without files64 KB in total, up to 200 fields, 10,000 characters per value, 100 values per list
FilesUp to 10 per submission, 10 MB each

Examples

JSON

cURL
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

Node.js
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
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:

200 OK
{
  "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:

403 Forbidden
{
  "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.

Made with Modulify