Formcrest
Log inGet started

HTML

The simplest way to use Formcrest: a plain HTML form that POSTs straight to your endpoint. No JavaScript, no build step.

The form

Point your form's action at your endpoint and set method="POST". The endpoint accepts a normal application/x-www-form-urlencoded or multipart/form-data body, so a standard browser form submission just works. Replace abc123 with your form ID from the dashboard.

<form action="https://api.formcrest.com/v1/submit/abc123" method="POST">
  <label>
    Email
    <input type="email" name="email" required />
  </label>

  <label>
    Message
    <textarea name="message" required></textarea>
  </label>

  <!-- Honeypot: leave empty. Bots fill it in and get rejected. -->
  <input
    type="text"
    name="_honey"
    style="display:none"
    tabindex="-1"
    autocomplete="off"
  />

  <button type="submit">Send</button>
</form>

Every field with a name is captured and included in the submission. Use whatever field names make sense for your form — there are no required field names except the ones you mark required in your own markup.

The honeypot field

The hidden _honey input is a spam trap. Real visitors never see it, so they leave it blank; many bots fill in every field they find and are silently rejected. Keep it hidden with CSS (not type="hidden"), set tabindex="-1", and turn off autocomplete so browsers don't populate it. The names _gotcha, botfield, url, and website are also recognized as honeypots, but _honey is the recommended one. See Spam protection for the full picture.

What happens on submit

For a normal HTML form post, a successful submission returns a 303 redirect. By default the visitor lands on our hosted thank-you page at /thanks. If you've set a success URL on the form, they're redirected there instead.

If something goes wrong, the visitor is redirected to your form's error URL (when one is configured), with a ?error=CODE query parameter appended so you can show a relevant message. See Error codes for the list of codes.

Custom success and error redirects

Set the success and error URLs in the dashboard under your form's settings — see Form configuration. Once a success URL is configured, successful submissions redirect there instead of the default /thanks page; once an error URL is configured, failed submissions redirect there with ?error=CODE.

Access key

If the form owner has required an access key, include it as a field named access_key. Submissions without a valid key are rejected.

<input type="hidden" name="access_key" value="your-access-key" />

Test it with curl

You can exercise the endpoint without a browser. A plain form-encoded post follows the same redirect behavior as the browser; add Accept: application/json to get a JSON response back instead.

curl -i https://api.formcrest.com/v1/submit/abc123 \
  -d "email=test@example.com" \
  -d "message=Hello from curl" \
  -d "_honey="

To see the JSON response shape instead of a redirect:

curl https://api.formcrest.com/v1/submit/abc123 \
  -H "Accept: application/json" \
  -d "email=test@example.com" \
  -d "message=Hello from curl"
# => { "ok": true, "submissionId": "..." }

Next steps