> For the complete documentation index, see [llms.txt](https://docs.forms.md/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forms.md/getting-started/spam-protection.md).

# Spam protection

## Set up Google reCAPTCHA

Use the built-in Google reCAPTCHA integration to protect against spam and fraudulent responses. To set up spam protection, use the `recaptcha` [option](/getting-started/options.md) and set your `siteKey` during instantiation. [Learn how to create the site key](https://cloud.google.com/recaptcha/docs/create-key-website) (also known as a reCAPTCHA key). Once this is done, your forms will be protected.

{% hint style="info" %}
Only reCAPTCHA `v3` is supported.
{% endhint %}

```javascript
import { Composer, Formsmd } from "formsmd";

const composer = new Composer({
  id: "my-form"
});
 
composer.choiceInput("position", {
  question: "What's your position?",
  choices: ["Product Manager", "Software Engineer", "Founder", "Other"],
  required: true
});
 
// Set the site key during instantiation
const formsmd = new Formsmd(
  composer.template,
  document.getElementById("my-form-container"),
  {
    recaptcha: {
      siteKey: "<YOUR_RECAPTCHA_KEY>"
    }
  }
);
formsmd.init();
```

***

## The `recaptcha` option

The `recaptcha` option has the following parameters:

| Name            | Type                                            | Description                                                     |
| --------------- | ----------------------------------------------- | --------------------------------------------------------------- |
| `siteKey`       | `string`                                        | Google reCAPTCHA site key.                                      |
| `action`        | `string`                                        | The action name. Default is `"submit"`.                         |
| `badgePosition` | `"bottomleft"` \| `"bottomright"` \| `"inline"` | The position of the reCAPTCHA badge. Default is `"bottomleft"`. |
| `hideBadge`     | `boolean`                                       | Whether to hide the reCAPTCHA badge. Default is `false`.        |

### Hide the badge

Set the `hideBadge` parameter to `true` to hide the reCAPTCHA badge.

```javascript
const formsmd = new Formsmd(
  composer.template,
  document.getElementById("my-form-container"),
  {
    recaptcha: {
      siteKey: "<YOUR_RECAPTCHA_KEY>",
      hideBadge: true
    }
  }
);
formsmd.init();
```

{% hint style="warning" %}
You need to manually include links to Google's privacy policy and terms of service if you decide to hide the reCAPTCHA badge. [Learn more](https://developers.google.com/recaptcha/docs/faq#id-like-to-hide-the-recaptcha-badge.-what-is-allowed).
{% endhint %}

***

## Server-side validation

{% hint style="info" %}
Reference: <https://developers.google.com/recaptcha/docs/verify>
{% endhint %}

Once Google reCAPTCHA has been set up, each form submission will contain an extra field called `_captcha`. This is the token that needs to be verified by sending the following request:

* **URL:** `https://www.google.com/recaptcha/api/siteverify`
* **Method:** `POST`&#x20;

| POST Parameter        | Description                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `secret` (required)   | The shared key between your site and reCAPTCHA.                                                                       |
| `response` (required) | The user response token provided by the reCAPTCHA client-side integration on your site. This is the `_captcha` token. |
| `remoteip`            | Optional. The user's IP address.                                                                                      |

The response is a JSON object:

```json
{
  "success": true|false,
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}
```