Submit JSON with hCaptcha

hCaptcha is a great spam-blocking alternative to Google reCAPTCHA with a focus on privacy, customization, and control.

Before getting started make sure to pull up the hCaptcha documentation for reference.

✨🤖🚦 hCaptcha is available on all paid plans

Get a Site Key and Secret Key

  1. Head to the hCaptcha website
  2. Create a new site, or select an existing one.
  3. Copy your sitekey and secret key.

Integrate hCaptcha with your front end

  1. Insert the hCaptcha script in your HTML's <head> tag.
<script src="https://js.hcaptcha.com/1/api.js" async defer></script>
  1. Render the client-side integration.

Don't forget to check out hCaptcha's official instructions for more info:

You must add an empty DOM container where the hCaptcha widget will be inserted automatically. The container is typically a <div> and must have a class h-captcha and a data-sitekey attribute set to your public site key.

<div class="h-captcha" data-sitekey="your_site_key"></div>

⚡️ OR ⚡️ if you're using a JS framework there is likely a package that will make the integration easier:

3. Pass your token along with your submission

Once the hCaptcha widget is setup, you can send the hCaptcha response token to our API in two ways.

  1. It can be passed along in the request body via a h-captcha-response property. This is the hCaptcha's default behavior and requires no additional config from you.
    document.getElementById('myForm').addEventListener('submit', async function (e) {
      const formData = new FormData(this);
      const data = Object.fromEntries(formData)
      // data is something like { ..., 'h-captcha-response': 'xxxxxx'}
      const response = await fetch('https://api.submitjson.com/v1/submit/XxXx', {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          'X-API-Key': 'sjk_xxx',
        body: { data },
      const submission = await response.json()
  2. If your situation requires more versatility, it can be added to the submission options with a hcaptchaToken key. For this example we'll use the JS client.
    await sj.submit({ name: 'Zoro', loves: 'Getting lost' }, {
      hcaptchaToken: 'xxxxxxxxxx'

Now that you've integrated hCaptcha with your front-end it's time to validate the token.

4. Validate the server-side response

We've got you all covered here. Follow these instructions to set it and forget it:

  1. Head to your endpoint's security settings
  2. Select hCaptcha as your CAPTCHA provider
  3. Paste in your secret key, and click Save

🚛✨💚 Nice job, submissions to your endpoint are now validated with hCaptcha