jQuery

It builds a FormData from the form, posts it and shows formcarry’s answer, and the same request carries files, a spam blocker token and validation errors.

Prerequisites

Before you start, you need:

A formcarry account. Sign up is free.
A form in the dashboard. Its endpoint is on the form’s Setup page. The examples use https://formcarry.com/s/AbC123xyz; put yours in its place.

The request

To send a form with jQuery, build a FormData from the form element, post it with $.ajax, and send Accept: application/json so the answer comes back as JSON:

<form class="formcarryForm" action="https://formcarry.com/s/AbC123xyz" method="POST">
  <input type="text" name="name">
  <input type="email" name="email">
  <textarea name="message"></textarea>
  <button type="submit">Send</button>
</form>

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.7.1/jquery.min.js"></script>
<script>
  $(function () {
    $(".formcarryForm").submit(function (e) {
      e.preventDefault();

      $.ajax({
        type: "POST",
        url: $(this).attr("action"),
        data: new FormData(this),
        dataType: "json",
        processData: false,
        contentType: false,
        headers: { Accept: "application/json" },
        success: function (response) {
          alert(response.message); // We received your submission
        },
        error: function (xhr) {
          alert(xhr.responseJSON.message);
        }
      });
    });
  });
</script>

Every field needs a name, because FormData reads the fields from the elements and formcarry stores each value under its name. The email field is the visitor’s address, so it becomes the reply to address of your notification and the recipient of the auto response. Set processData: false and contentType: false rather than leaving the defaults, otherwise jQuery tries to serialise the FormData itself and the request fails before it is sent. A stored submission answers with code: 200. jQuery routes every status outside 2xx to error, so a refused submission’s answer is in xhr.responseJSON, with the reason in message, see What every form needs. Without a file input, $(this).serialize() posts the same fields as application/x-www-form-urlencoded, with no processData or contentType to set:

$.ajax({
  type: "POST",
  url: $(this).attr("action"),
  data: $(this).serialize(),
  dataType: "json",
  headers: { Accept: "application/json" },
  // success and error as above
});

serialize() leaves file inputs out, so a form that uploads keeps the FormData request.

JSON

To send JSON instead, collect the fields into an object, JSON.stringify it, and set contentType: "application/json":

var fields = Object.fromEntries(new FormData(this));

$.ajax({
  type: "POST",
  url: $(this).attr("action"),
  data: JSON.stringify(fields),
  contentType: "application/json",
  dataType: "json",
  headers: { Accept: "application/json" },
  // success and error as above
});

The keys are the field names formcarry stores.

Files

A FormData built from the form carries its file inputs, so the first request uploads them as is. To take one file in one field and several in another, add the inputs to the form; the same $.ajax options send them:

<input type="file" name="attachment">
<input type="file" name="attachments" multiple>

Keep contentType: false rather than setting multipart/form-data yourself, otherwise the multipart boundary is missing and the upload fails. For File objects from elsewhere, such as a Dropzone with its own upload turned off, append each one under its own name:

<script src="https://unpkg.com/dropzone@5/dist/min/dropzone.min.js"></script>
<link rel="stylesheet" href="https://unpkg.com/dropzone@5/dist/min/dropzone.min.css">

<!-- inside the form -->
<div id="attachments" class="dropzone"></div>

<script>
  Dropzone.autoDiscover = false;

  $(function () {
    var dropzone = new Dropzone("#attachments", {
      url: "/dummy",
      autoProcessQueue: false,
      uploadMultiple: true,
      parallelUploads: 10,
      maxFiles: 10,
      addRemoveLinks: true
    });

    $(".formcarryForm").submit(function (e) {
      e.preventDefault();

      var formData = new FormData(this);
      var files = dropzone.getAcceptedFiles();
      for (var i = 0; i < files.length; i++) {
        formData.append("file-" + i, files[i]);
      }

      $.ajax({
        type: "POST",
        url: $(this).attr("action"),
        data: formData,
        dataType: "json",
        processData: false,
        contentType: false,
        headers: { Accept: "application/json" },
        // success and error as above
      });
    });
  });
</script>

autoProcessQueue: false keeps Dropzone from posting to url itself, and getAcceptedFiles() returns what the visitor dropped. For a small file inside the JSON request, read it as a data URL and give it its own key, never an array:

var form = this;
var fields = Object.fromEntries(new FormData(form));
var reader = new FileReader();

reader.onload = function () {
  fields.attachment = reader.result;
  $.ajax({
    type: "POST",
    url: $(form).attr("action"),
    data: JSON.stringify(fields),
    contentType: "application/json",
    dataType: "json",
    headers: { Accept: "application/json" },
    // success and error as above
  });
};
reader.readAsDataURL(form.elements.attachment.files[0]);

Use data URLs for small files. Using them with larger files bloats the request by about a third and reaches the 50 MB limit sooner.

Files are stored on paid plans only. Free plans store the rest of the submission without them.

Validation errors

A 422 carries errors, one entry per failing field, each with a message. To show each one next to its field, and every other refusal in an alert:

error: function (xhr) {
  var answer = xhr.responseJSON;
  if (answer.code === 422) {
    $.each(answer.errors, function (name, error) {
      var field = $('[name="' + name + '"]');
      field.addClass("fc-field-error");
      $("<span></span>").addClass("fc-field-error-message").text(error.message).insertAfter(field);
    });
  } else {
    alert(answer.message); // 403, 429 and the rest
  }
}

Read the 422 in error rather than in success, otherwise the handler never runs. To clear the marks before the next attempt, remove them at the top of the submit handler:

$(".fc-field-error-message").remove();
$(".fc-field-error").removeClass("fc-field-error");

Clear them on every submit rather than only on success, otherwise old messages stay next to fields that now pass.

Spam blocker

To add a challenge, load the vendor’s script, put a div with the widget class and data-sitekey inside the form, and paste the secret key into the form’s settings under Form Security:

Challenge	Script	Widget class	Token field
reCAPTCHA v2	`https://www.google.com/recaptcha/api.js`	`g-recaptcha`	`g-recaptcha-response`
reCAPTCHA v3	`https://www.google.com/recaptcha/api.js?render=SITE_KEY`	none	`g-recaptcha-response`
hCaptcha	`https://js.hcaptcha.com/1/api.js`	`h-captcha`	`h-captcha-response`
Turnstile	`https://challenges.cloudflare.com/turnstile/v0/api.js`	`cf-turnstile`	`cf-turnstile-response`

With reCAPTCHA v2:

<script src="https://www.google.com/recaptcha/api.js" async defer></script>

<!-- inside the form, before the submit button -->
<div class="g-recaptcha" data-sitekey="SITE_KEY"></div>

The widget adds a field named g-recaptcha-response to the form, so the FormData request carries the token as is, and Object.fromEntries puts it into the JSON request too. With reCAPTCHA v3 there is no widget: call grecaptcha.execute("SITE_KEY", { action: "submit" }) when the visitor submits and put what it returns into a hidden input named g-recaptcha-response. To hold the request until the visitor has passed the challenge, check the token at the top of the submit handler:

if (!$(this).find('[name="g-recaptcha-response"]').val()) {
  alert("Complete the challenge first");
  return;
}

Refuse to send while the token is empty rather than posting anyway, otherwise formcarry answers 403 for reCAPTCHA or 400 for the others. Add localhost to the challenge’s allowed domains while you test.

The submit button

To stop a second submit while the request runs, disable the button before $.ajax and enable it again in complete:

var button = $(this).find('button[type="submit"]').first();
button.prop("disabled", true);

$.ajax({
  // the options above
  complete: function () {
    button.prop("disabled", false);
  }
});

complete runs after success and error alike, so the button comes back after a refused submission too. Disable the button rather than trusting one click, otherwise the second click gets a 429: 1 submission per 15 seconds per form per IP address. To show that the request is running, swap the button text for a spinner and put the text back in complete:

var button = $(this).find('button[type="submit"]').first();
var buttonText = button.text();
var loader = $('<svg fill="#fff" width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><style>.spinner_ajPY{transform-origin:center;animation:spinner_AtaB .75s infinite linear}@keyframes spinner_AtaB{100%{transform:rotate(360deg)}}</style><path d="M12,1A11,11,0,1,0,23,12,11,11,0,0,0,12,1Zm0,19a8,8,0,1,1,8-8A8,8,0,0,1,12,20Z" opacity=".25"/><path d="M10.14,1.16a11,11,0,0,0-9,8.92A1.59,1.59,0,0,0,2.46,12,1.52,1.52,0,0,0,4.11,10.7a8,8,0,0,1,6.66-6.61A1.42,1.42,0,0,0,12,2.69h0A1.57,1.57,0,0,0,10.14,1.16Z" class="spinner_ajPY"/></svg>');

button.html(loader);
button.prop("disabled", true);

$.ajax({
  // the options above
  complete: function () {
    button.html(buttonText);
    button.prop("disabled", false);
  }
});

Put the text back in complete rather than in success, otherwise a refused submission leaves the spinner in the button.

Reset

To clear the fields after a stored submission, reset the form in success:

var form = $(this);

$.ajax({
  // the options above
  success: function (response) {
    if (response.code === 200) {
      alert(response.message);
      form[0].reset();
    }
  }
});

Reset in success rather than in complete, otherwise a refused submission clears what the visitor typed.

What’s next

Field validations: the rules you can set per field.
Spam protection: the challenges, the filter and the honeypot.
Email notifications: the auto response the visitor gets, keyed on email.

Stuck? Write to help@formcarry.com. Include the form id.

Getting Started

Features

Email Configuration

Integrations

Frameworks

Site builders

Build with AI

Connect over MCP

Prerequisites

The request

JSON

Files

Validation errors

Spam blocker

The submit button

Reset

What’s next

​Prerequisites

​The request

​JSON

​Files

​Validation errors

​Spam blocker

​The submit button

​Reset

​What’s next

Prerequisites

The request

JSON

Files

Validation errors

Spam blocker

The submit button

Reset

What’s next