# Protecting contact & lead forms

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Contact, quote-request, demo-request and newsletter forms are the most common target for spam bots and for low-cost human spam. This page sets up the widget so that Sentinel classifies the form's fields when it verifies the solution, and shows the backend code that accepts, flags or rejects each submission based on the signed result.

Prerequisites: a running Sentinel with an active license, and an admin user who can edit security groups and API keys in the account. See [Get started](/docs/sentinel/v2/get-started/).

<Callout type="note" title="Changed in v2">

Sentinel Forms (`/v1/submit/:slug`) were removed. Your form posts to your own endpoint, and your backend verifies the widget's payload. Sentinel never receives or stores the submission itself. See [Removed features](/docs/sentinel/v2/upgrade/#removed-features).

## What you're defending against

| Threat | What stops it |
| --- | --- |
| Bots that post straight to your form endpoint | No valid widget payload: your backend rejects the request before it reads the form. |
| Headless browsers that solve the proof-of-work | Rate limits and header-entropy limits per device, plus a code challenge and a harder proof-of-work for risky clients (the **Recommended** preset). |
| Spam written by people or scripts: SEO offers, crypto and pharma pitches, link drops | The text rules, the phishing list, similarity with your own spam examples and, optionally, the AI decider. |
| Injection probes in form fields | The five injection rules, which make the classification `BAD`. |
| The same message sent from many IPs | `CAMPAIGN`, without any training data. |
| Tampered or replayed submissions | `fieldsHash` binds the classification to the submitted values, and Sentinel accepts each payload once. |

## Recommended configuration

### Security group for the form

Create a `public` security group for your contact forms and apply these presets from **Security groups → Create security group → Templates**:

| Preset | Kind | Why |
| --- | --- | --- |
| [Recommended](/docs/sentinel/v2/policies/presets/#recommended) | Base | Threat blocking, a rate limit of `50/10m` per device, header-entropy limit, and escalation to a code challenge for risky or penalized clients. |
| [Form fields](/docs/sentinel/v2/policies/presets/#form-fields) | Add-on | Makes the widget send the form's fields to `POST /v2/verify`, so the signed classification includes the email, text, injection and similarity rules. |
| [Allowed origins](/docs/sentinel/v2/policies/presets/#allowed-origins) | Add-on, optional | Keeps the key off other websites. |

Then add your own rule after the presets, to choose the training groups that similarity compares with and, optionally, to ask the AI decider whether a message fits the form:

```json
{
"name": "contact-classifier",
"action": "set",
"set": [
{ "field": "classifier.similarityGroups", "value": "contact_spam" },
{ "field": "classifier.ai", "value": "true" },
{ "field": "classifier.aiPurpose", "value": "Contact form of a B2B software company: questions about products, pricing, demos and support" }
]
}
```

The group's rules then run in this order:

```text
preset:origins:allow
preset:forms:classifier
preset:recommended:threats
preset:recommended:base
preset:recommended:elevated
preset:recommended:high
contact-classifier
```

- Leave out the two `classifier.ai*` entries if the server has no `[classifier.ai]` provider. See [AI decider](/docs/sentinel/v2/features/ai-decider/).
- For a form where most visitors use free email providers, such as a newsletter sign-up, apply **Form fields (consumer sign-ups)** instead of **Form fields**. It also disables `FREE_PROVIDER` and `PRIVACY_RELAY`.
- Every form that should be classified differently needs its own `public` key in its own group, or conditions on the `set` rule. See [Classify each form differently](/docs/sentinel/v2/policies/security-rules/#classify-each-form-differently).

### Server configuration

The text, injection and `CAMPAIGN` rules need no configuration. For similarity that catches reworded spam, choose an embedding model, and let Sentinel queue texts that the text rules find spammy so you can turn them into training data:

```toml
[similarity]
provider = "local"    # ONNX model, ~135 MB download at startup

[similarity.suggestions]
enabled = true        # stores message text for review; off by default
```

See [Similarity & training data](/docs/sentinel/v2/features/similarity/#enabling-it) and [`[similarity]`](/docs/sentinel/v2/reference/configuration/#similarity).

### API keys

| Key | Group | Used by |
| --- | --- | --- |
| `public` | The contact-form group above. Set **Request logging** to **Verification**. | The widget |
| `restricted` | A backend group with the [Backend API (allowed IPs)](/docs/sentinel/v2/policies/presets/#backend-api-allowed-ips) preset. See [Backend & API protection](/docs/sentinel/v2/use-cases/api-protection/). | Your backend, for `POST /v2/verify/signature` and `POST /v2/training-data/_feedback` |

See [Managing API keys](/docs/sentinel/v2/policies/api-keys/).

## Integration steps

### Step 1 — Add the widget to the form

Install widget 3.7.0 or later in your page as described in [Widget integration](/docs/integration/widget/). Then point it at Sentinel with the `public` key, and tag the challenge with a custom parameter so your backend can check that the payload was made for this form:

```html
<form action="/contact" method="post">
<input type="text" name="name" autocomplete="name" required />
<input type="email" name="email" autocomplete="email" required />
<input type="text" name="company" autocomplete="organization" />
<textarea name="message" required></textarea>
<input type="text" name="orderNumber" data-no-spamfilter />
<altcha-widget
challenge="https://sentinel.example.com/v2/challenge?apiKey=key_…&params.formId=contact"
></altcha-widget>
<button type="submit">Send</button>
</form>
```

- **Which fields are sent.** The widget sends the non-empty values of text inputs, email inputs and textareas, except those marked `data-no-spamfilter`. Password, phone and other inputs aren't sent. To pick fields by name instead, set `serverVerificationFieldNames`. See [Which fields the widget sends](/docs/sentinel/v2/integrate/widget/#which-fields-the-widget-sends).
- **The email field.** Sentinel checks the domain of the email address (`MX`, `DISPOSABLE`, `FREE_PROVIDER`, …): the field named `email`, or else a value shaped like an address. Widgets before 3.7.0 don't send `type="email"` inputs; with those, use `type="text" inputmode="email"`, or classify the address from your backend with `POST /v2/classifier`. See [Classifier](/docs/sentinel/v2/features/classifier/#using-the-api).
- **Fields that aren't prose.** Mark order numbers, phone numbers and similar fields with `data-no-spamfilter`, so their values don't feed the text rules.
- **No `fields=1`.** The **Form fields** preset's `classifier.fields` rule overrides the challenge URL's `fields` parameter.

See [Widget integration](/docs/sentinel/v2/integrate/widget/) and [Custom parameters & fields](/docs/sentinel/v2/integrate/parameters/).

### Step 2 — Verify and decide on your backend

Verify the payload with `POST /v2/verify/signature` before you read the form. This Express handler uses `altcha-lib` 2.9.0 or later, which returns `verificationData` with flat keys such as `params.formId`:

```ts
import { verifyFieldsHash, verifyServer } from 'altcha-lib';
import express from 'express';

const app = express();
app.use(express.urlencoded({ extended: false }));

app.post('/contact', async (req, res) => {
const result = await verifyServer({
payload: req.body.altcha,
url: 'https://sentinel.example.com/v2/verify/signature',
apiKey: { id: 'key_…', secret: process.env.SENTINEL_API_KEY_SECRET! }, // restricted key
});
const data = result.verified ? result.verificationData : null;
if (
!data ||
data['params.formId'] !== 'contact' ||
!data.fields ||
!(await verifyFieldsHash({ formData: req.body, fields: data.fields, fieldsHash: String(data.fieldsHash) }))
) {
res.status(400).send('Verification failed. Please try again.');
return;
}

const reasons = data.reasons ?? [];
if (data.classification === 'BAD') {
// Spam, injection, a phishing link or a strong similarity match. Keep a record if you
// want to review rejections, but don't deliver the message.
res.status(422).send('Your message could not be sent.');
return;
}
const review = data.classification === 'NEUTRAL' || reasons.includes('CAMPAIGN');
await saveMessage(req.body, { review, score: data.score, reasons }); // your code
res.send('Thank you! We will get back to you soon.');
});

app.listen(8080);
```

- **`verified` alone isn't enough.** It means the proof-of-work and any code challenge passed. Spam written by a person verifies too; the classification is what tells it apart.
- **Require `fields`.** With the **Form fields** preset, the widget sends the form's fields, so a payload from your form has `fields` and `fieldsHash`. Requiring them stops a client from verifying an empty form and then submitting different text.
- **Pick your own threshold.** `classification` is `GOOD` below a score of 1, `NEUTRAL` below 2 and `BAD` from 2. Use `data.score` for a finer cut. See [Decide from the classification](/docs/sentinel/v2/integrate/verification/#decide-from-the-classification).
- **Replays.** `POST /v2/verify/signature` accepts each payload once and answers `PAYLOAD_ALREADY_USED` after that, so a resubmitted form fails verification.

Your backend sends any notification emails or CRM updates; Sentinel only classifies.

### Step 3 — Feed spam back into training data

When someone on your team marks a delivered message as spam, or restores a rejected one, send the text to `POST /v2/training-data/_feedback` with the backend key. The next reworded copy then matches the `contact_spam` group:

```bash
curl https://sentinel.example.com/v2/training-data/_feedback \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{"group": "contact_spam", "label": "positive", "text": "We offer guaranteed first-page Google rankings for your website. Reply for a free audit and pricing."}'
```

```json
{ "data": { "duplicate": false, "id": "trd_…" } }
```

Use `"label": "negative"` for a legitimate message that was flagged. A match on a positive sample with weight `1` (the feedback default) makes the classification `BAD`. Samples are up to 4000 characters. See [Feedback from your application](/docs/sentinel/v2/features/similarity/#feedback-from-your-application).

## Monitoring & tuning

- **Start in monitor mode.** Apply the presets with **Apply in monitor mode** checked, watch the group's **Activity** tab for a few days, then turn them on. **Form fields** changes only what `/v2/verify` signs, so it's safe to apply live. See [Monitor mode](/docs/sentinel/v2/policies/presets/#monitor-mode).
- **Find false positives.** With request logging on, each verification stores its `triggeredRules`. The `triggeredRules` breakdown of `POST /v2/request-logs/_stats` shows which rules fire most for the form's key. A rule that fires on normal messages, such as `CURRENCY` on a quote form that mentions budgets, goes into `classifier.disableRules` in the group's `contact-classifier` rule. See [Request logs & analytics](/docs/sentinel/v2/operations/request-logs/#read-statistics).
- **Review suggestions.** Under **Training Data → Suggestions**, accept texts that the text rules caught into `contact_spam`, so their rewordings are caught too. See [Training suggestions](/docs/sentinel/v2/features/similarity/#training-suggestions).
- **Watch the friction.** The `protectionLevel` breakdown shows how many visitors got a code challenge. If too many legitimate visitors do, switch the base preset to **Recommended without code challenge**.
- **Alert on spikes.** The `verification_failures` alert fires when an account's failed verifications rise well above their baseline. See [Alerts](/docs/sentinel/v2/operations/alerts/#rules).

## Related

- [Verifying submissions](/docs/sentinel/v2/integrate/verification/)
- [Spam, profanity & injection detection](/docs/sentinel/v2/features/text-analysis/)
- [Similarity & training data](/docs/sentinel/v2/features/similarity/)
- [AI decider](/docs/sentinel/v2/features/ai-decider/)
- [Security presets](/docs/sentinel/v2/policies/presets/)
- [Protecting user registration](/docs/sentinel/v2/use-cases/registration/)
