Set up Google reCAPTCHA

Add reCAPTCHA v2 checkbox or v3 invisible verification to your forms.

What is reCAPTCHA?

reCAPTCHA is Google's bot detection service. It comes in two versions that work differently:

• reCAPTCHA v2 (checkbox) — shows an "I'm not a robot" checkbox on your form. Users click it and sometimes solve an image puzzle (like "select all traffic lights"). It is the most widely recognized captcha on the web.
• reCAPTCHA v3 (invisible) — runs entirely in the background with no visible widget. Google monitors how the user interacts with the page and assigns a score from 0.0 (likely bot) to 1.0 (likely human). Your form is protected without the user doing anything at all.

Both versions are free to use and supported on all Pro plans.

Step 1: Get your keys from Google

1. Go to the Google reCAPTCHA admin console.
2. Click the + button to register a new site.
3. Enter a label (e.g., "Contact Form" or "My Website").
4. Choose the reCAPTCHA type:
   • Select reCAPTCHA v2 and then "I'm not a robot" Checkbox if you want the visible checkbox.
   • Select reCAPTCHA v3 if you want invisible, score-based verification.
5. Under Domains, add:
   • Your own domain (e.g., yoursite.com)
   • formblade.com if you use the hosted form page
6. Accept the terms and click Submit.
7. Google will show you two keys — copy both:
   • Site Key (public, goes in your HTML)
   • Secret Key (private, stays on the server)

Step 2: Add keys in FormBlade

1. Open your form in the FormBlade dashboard.
2. Go to the Settings tab.
3. Scroll down to the Captcha section.
4. Select reCAPTCHA v2 or reCAPTCHA v3 from the dropdown.
5. Paste your Site Key into the Site Key field.
6. Paste your Secret Key into the Secret Key field.
7. If you chose v3, set the Score Threshold (more on this below).
8. Click Save.

If you use a hosted form, the captcha widget is added automatically. If you use a custom HTML form, you need to add the widget code yourself (see below).

reCAPTCHA v2: how the checkbox works

When a user loads your form, they see a small "I'm not a robot" checkbox. After clicking it, Google may show a quick image challenge if the user's behavior seems suspicious. Once the user passes, a hidden g-recaptcha-response field is added to the form. FormBlade verifies this token server-side using your Secret Key before accepting the submission.

There is nothing to configure beyond the site and secret keys. Every user who fails the challenge is blocked.

reCAPTCHA v3: invisible scoring

With v3, there is no visible widget. Google silently scores every visitor based on behavior patterns — mouse movements, browsing history, how fast the form was filled out, and other signals. The score ranges from 0.0 (very likely a bot) to 1.0 (very likely human).

In your form settings, the Score Threshold (also called "min score") controls the cutoff:

The default threshold is 0.5. Start there and lower it if legitimate users report being blocked.

The "fail reject" toggle

In the Captcha section of your form settings, you will see a Fail Reject toggle. When enabled (the default), any submission that fails captcha verification is rejected outright — the user sees an error and the submission is not stored. When disabled, failed submissions are still accepted but marked as spam in your dashboard. This lets you review borderline cases instead of losing them entirely.

Add reCAPTCHA v2 to a custom HTML form

If you are not using a hosted form, add the reCAPTCHA script and widget div to your page:

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

<form action="https://formblade.com/f/contact" method="POST">
  <label>Name</label>
  <input type="text" name="name" required>

  <label>Email</label>
  <input type="email" name="email" required>

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

  <!-- reCAPTCHA v2 widget -->
  <div class="g-recaptcha" data-sitekey="YOUR_SITE_KEY"></div>

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

Replace /f/contact with your own form link from the dashboard.

Replace YOUR_SITE_KEY with your actual site key. The widget renders the checkbox automatically. When the user completes the challenge, a hidden g-recaptcha-response field is injected into the form.

Add reCAPTCHA v3 to a custom HTML form

Since v3 is invisible, there is no widget div. Instead, you load the script with your site key and execute it on form submit:

<script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>

<form id="myForm" action="https://formblade.com/f/contact" method="POST">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <textarea name="message" required></textarea>
  <input type="hidden" name="g-recaptcha-response" id="recaptchaResponse">
  <button type="submit">Send</button>
</form>

<script>
document.getElementById('myForm').addEventListener('submit', function(e) {
  e.preventDefault();
  grecaptcha.ready(function() {
    grecaptcha.execute('YOUR_SITE_KEY', {action: 'submit'}).then(function(token) {
      document.getElementById('recaptchaResponse').value = token;
      document.getElementById('myForm').submit();
    });
  });
});
</script>

Replace /f/contact with your own form link from the dashboard.

Replace both instances of YOUR_SITE_KEY with your actual site key. The script intercepts the form submission, requests a token from Google, injects it into the hidden field, and then submits the form. FormBlade checks the token and score server-side.

Tips

• v3 provides better UX — users never see a challenge or checkbox. It is the best choice when you want invisible protection without any friction.
• v2 is more reliable for stopping targeted bots — the visible challenge is harder for bots to bypass. Use it for high-value forms like registration or payment pages.
• Test with Google's test keys first — before going live, use the test keys (listed above) to verify your integration works. Test keys always pass, so you can confirm the flow without worrying about scores or challenges.
• You can check score distributions — log in to the reCAPTCHA admin console to see what scores your visitors are getting. This helps you tune the threshold.
• Add both domains — if you use both a custom HTML form on your site and a hosted form on formblade.com, add both domains in the Google admin console.

Troubleshooting

Captcha widget not showing (v2)

If the checkbox does not appear on your page, check the following:

• Make sure the api.js script tag is present and loading (check your browser's Network tab for errors).
• Verify that your domain is listed in the reCAPTCHA admin console. The domain in the console must match the domain where the form is displayed.
• Check for JavaScript errors in the browser console — another script may be conflicting with reCAPTCHA.

Submissions being blocked unexpectedly (v3)

If legitimate users are getting rejected:

• Lower the score threshold — try 0.3 instead of 0.5. Users on VPNs, Tor, or shared networks often get lower scores.
• Turn off Fail Reject — set submissions to be marked as spam instead of rejected, so you can review them in the dashboard.
• Check the reCAPTCHA admin console for score distributions. If most of your legitimate users score below 0.5, you need a lower threshold.

Secret key error

If submissions fail with a captcha verification error, double-check that you pasted the Secret Key (not the Site Key) into the Secret Key field in FormBlade. The two keys are not interchangeable.