# 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
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forms.md/getting-started/spam-protection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.