Developer documentation
Two steps: the widget in your form, then a server-side check of the token before you process anything. The API answers like reCAPTCHA and Turnstile, plus an action and reasons.
Quick start
1. Add the widget to your form. Replace the site key with your own from the dashboard.
<script src="https://formconfirmed.com/v1/widget.js" async defer></script>
<form method="post" action="/contact" data-formconfirmed-ajax>
<label>Name <input name="name" autocomplete="name"></label>
<label>Email <input type="email" name="email" autocomplete="email"></label>
<label>Message <textarea name="message" required></textarea></label>
<div class="fcp-widget" data-sitekey="fcp_pub_..." data-purpose="contact"></div>
<button type="submit">Send</button>
</form>
2. Before sending or storing the submission, send the token to /v1/verify from your server. The secret key stays on the server.
<?php
$ch = curl_init('https://formconfirmed.com/v1/verify');
curl_setopt_array($ch, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 5,
CURLOPT_POSTFIELDS => http_build_query([
'secret' => getenv('FCP_SECRET'),
'response' => $_POST['fcp-response'] ?? '',
'remoteip' => $_SERVER['REMOTE_ADDR'] ?? '',
'content' => $_POST['message'] ?? '',
'name' => $_POST['name'] ?? '',
'email' => $_POST['email'] ?? '',
'expected_purpose' => 'contact',
]),
]);
$res = json_decode((string)curl_exec($ch), true);
$codes = is_array($res) ? (array)($res['error-codes'] ?? []) : [];
$noCheck = array_intersect($codes, ['invalid-input-secret', 'missing-input-secret', 'site-paused', 'service-disabled', 'bad-request']);
if (!is_array($res) || !in_array($res['action'] ?? '', ['allow', 'flag', 'block'], true) || $noCheck) {
$decision = 'hold'; // no clear answer (outage, setup error): never a pass
} elseif ($res['action'] === 'block') {
$decision = 'reject';
} elseif ($res['action'] === 'allow' && ($res['success'] ?? null) === true
&& !in_array('service_unavailable', (array)($res['reasons'] ?? []), true)) {
$decision = 'accept';
} else {
$decision = 'hold'; // flagged, or only the browser reported an outage
}
Complete, tested examples for PHP, Node.js, Python (Flask, Django), Ruby, Go, Java and .NET, all following the outage rule: github.com/LW-IT-Solutions/formconfirmed-examples
POST /v1/verify
https://formconfirmed.com/v1/verify
Send the fields as form data (application/x-www-form-urlencoded) or as JSON. Use a short timeout (5 seconds).
| Field | Meaning | |
|---|---|---|
secret | required | Your secret key (fcp_sec_…). Never put it in the page. |
response | required | The token from the form field fcp-response. Send it even if it is empty – do not reject a missing token yourself. |
remoteip | optional | IP address of the visitor. Sharpens rate and network signals. |
content | optional | Message text. Spam pre-filter in every plan, AI content check depending on plan and settings. Form data is processed briefly on our servers. AI checks use a temporary internal queue. |
email | optional | E-mail address from the form: disposable providers and domains without mail are recognised. |
name | optional | Name from the form (optional): names that look randomly generated, such as eGuFjDzGcwdwrWEFfnYH, are flagged. Form data is processed briefly on our servers. AI checks use a temporary internal queue. With content checking enabled, the AI also evaluates a masked name pattern, including registrations without a message. The actual name is not sent to the model. |
hp | optional | Value of the hidden field fcp-website (honeypot). |
expected_purpose | optional | The purpose the widget was signed for, e.g. contact, login, register. A token for another purpose is rejected. |
operation_id | optional | Stable ID of the business action (16–128 characters) – repeated requests do not count twice. Only together with expected_purpose. |
recipient | optional | Recipient of an action mail (e.g. password reset) for the per-recipient limits. |
form_mode | optional | interactive (default) or deferred for forms that are sent later. |
Response
{ "success": true, "score": 0.92, "action": "allow", "reasons": [],
"error-codes": [], "challenge_ts": "2026-11-06T09:41:12Z", "hostname": "example.com" }
success | true only if the action is allow; false for flag, block or an invalid request. |
score | Combined assessment from 0.0 (many suspicious signals) to 1.0 (no suspicious signals detected). This is not proof that a visitor is human. |
action | allow, flag or block – the recommended handling. |
reasons | Signals that led to the result, e.g. too_fast, honeypot_filled. |
error-codes | Technical errors, see below. |
challenge_ts | Time the task was solved (UTC). |
hostname | Host on which the widget ran. |
content | Only with content check: category and confidence. |
support_id | Opaque support reference for this API request, also returned as X-Formconfirmed-Support-ID. Present on application error responses too; quote this ID and the approximate time when contacting support. It contains no form data and is separate from the verdict ID used for feedback. |
Handling the action
- allow: process the submission normally.
- flag: do not process it silently – deliver it marked (spam folder, moderation).
- block: reject it and show a neutral error message.
Confirm processing reliably
- Allow: process normally. Confirm receipt only after your own delivery or storage operation has acknowledged it.
- Flagged or unclear: hold for review if durable storage is actually available. If storage fails, return an error instead of claiming receipt.
- Block: reject neutrally. Do not send an automatic reply to the supplied address for flagged or blocked submissions.
When the service cannot be reached
A timeout, network error, 5xx or invalid answer is never a pass. Hold the message marked for moderation or show an error asking to try again. Accept it normally only after an independent check of your own, for example an existing account check. In the dashboard you can set the outage behaviour per site.
Error codes
missing-input-secret | No secret key sent. |
invalid-input-secret | Unknown or revoked secret key. |
missing-input-response | No token sent. |
invalid-input-response | Token invalid, expired or already used. |
purpose-mismatch | The token was issued for another purpose. |
purpose-not-allowed | This purpose is not allowed for the site (dashboard setting). |
site-paused | The site is paused in the dashboard. |
service-disabled | The service is switched off temporarily. |
bad-request | Fields missing, too long or in the wrong format. |
service-unavailable | The widget could not reach the service – treat it like an outage. |
Forms sent with JavaScript
For forms sent with fetch or XMLHttpRequest, get the token first and send it in the field fcp-response:
const form = document.querySelector('form[data-formconfirmed-ajax]');
let busy = false;
if (form) form.addEventListener('submit', async (event) => {
event.preventDefault();
if (busy) return;
const data = new FormData(form);
// The widget capture handler fills this field before this handler runs.
if (!data.get('fcp-response')) return;
if (event.submitter && event.submitter.name) data.append(event.submitter.name, event.submitter.value);
let output = form.querySelector('[role="status"]');
if (!output) { output = document.createElement('p'); output.setAttribute('role','status'); form.appendChild(output); }
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 15000);
busy = true;
try {
const target = new URL(form.action, location.href);
if (target.origin !== location.origin) throw new Error('endpoint');
const response = await fetch(target.href, {method:'POST', body:data, signal:controller.signal});
if (!response.ok || !response.body) throw new Error('response');
const reader = response.body.getReader(), decoder = new TextDecoder();
let bytes = 0, text = '';
while (true) {
const part = await reader.read();
if (part.done) break;
bytes += part.value.byteLength;
if (bytes > 16384) throw new Error('size');
text += decoder.decode(part.value, {stream:true});
}
text += decoder.decode();
const receipt = JSON.parse(text);
if (!receipt || !['accepted','held'].includes(receipt.status)) throw new Error('receipt');
// Your backend returns this only after actual processing or durable storage.
output.textContent = receipt.status === 'held' ? 'Received for review.' : 'Received by your server.';
} catch (_) {
output.textContent = 'No confirmation obtained. The server may already have processed the message. Do not retry automatically.';
} finally { clearTimeout(timer); controller.abort(); busy = false; }
});
AJAX with one responsible submit handler
- This example is for a plain HTML form with exactly one AJAX handler. The widget capture handler waits for a token and fills fcp-response before the following submit handler runs. No second token() call is needed here.
- Keep CSRF protection, input validation and server-side /verify checks. Your server may return the example {status:"accepted"} or {status:"held"} only after processing or durable storage has actually succeeded.
- The deadline covers the network and response body after the widget releases submission. An error leaves processing uncertain; never retry automatically. Coordinate this flow with any framework submit handler.
remoteip behind a reverse proxy
- Use REMOTE_ADDR after your web server resolves the visitor address using your explicitly trusted proxies.
- Do not trust X-Forwarded-For from arbitrary senders. Allow only the proxy addresses you actually operate; trusting all proxies or accepting malformed CIDR entries is unsafe.
- remoteip is optional. Omit it if the visitor address cannot be determined reliably. Never copy sample network ranges into production without reviewing them.
WordPress
Download formconfirmed for WordPress (ZIP) · Full WordPress guide
- In WordPress, go to Plugins → Add Plugin → Upload Plugin. Upload the ZIP, click “Install Now” and then “Activate Plugin”. Older WordPress versions may call Add Plugin “Add New Plugin” or “Add New”.
- Open Settings → formconfirmed → “Settings” and choose “Connect with formconfirmed”.
- Open your formconfirmed account, compare the website and request code and approve the connection.
- Return to WordPress and complete the connection.
- Open the “Forms” tab, enable the forms you want to protect and save. New forms follow the default setting shown there. If you use a page cache, clear it after saving.
- As a visitor, open one of your protected forms, check for the formconfirmed badge and send a harmless test message. Check that it arrives.
- In the plugin, check that “Overview” shows a recent response. Marked submissions are listed under “Held messages”.
Manual keys (alternative)
Manual keys remain available under “Settings”. Add your website to your formconfirmed account, enter the site key and secret key and test the connection. The secret key belongs only on your server.
Already using the formexposed plugin? You can also set up formconfirmed under its Form protection tab.
Data protection
No cookies, nothing stored on the device, no fingerprint. Processed: the solved task, the filling time, whether the hidden field was filled and – if you send it – the message text, which is briefly processed on our servers, with a temporary internal queue for AI checks. IP addresses only shortened and as a daily changing hash. A text for your privacy policy is in the dashboard. The web server log retains the full IP address for 14 days.
Pre-filter and AI: what the plan covers
Form protection combines several checks. The plan alone does not determine a submission's result.
- Every plan
- The spam pre-filter checks message texts for recognisable patterns. It is separate from the additional AI content check.
- Additional AI content check
- It depends on the plan, settings and available allowance. The pre-filter can assess a text without requiring an AI check.
- Check unavailable
- An unavailable requested content check is not a positive result. Read action and reasons and explicitly handle flagged submissions on your server.
- Estimate your needs
- Compare your monthly checks, required AI checks and badge setting with the current plan cards. A recommendation does not book a plan or change a subscription.
Score, action and reasons
The score combines signals. It is neither a probability nor proof that a human wrote the message.
- success and action
- success is true only for action=allow. flag is not automatic approval. block rejects the submission; your integration implements the actual handling.
- score
- The value ranges from 0 to 1. A high value means few suspicious signals were detected. Do not derive fixed thresholds from a single demo result.
- reasons
- The list names detected signals. too_fast concerns an unusually short completion time; honeypot_filled concerns a filled hidden field. Reasons are not API error codes.
- Technical failure
- service_unavailable can appear as a reason; service-unavailable is an API error code. Check the relevant response field instead of treating a hyphen and underscore as interchangeable.
- Review false positives
- Unusual names, a VPN or a shared company connection do not prove abuse. Consider the reasons together with a legitimate counter-check.
From the form to a server decision
The browser and your server have different tasks. The secret stays on your server.
- 1. Browser
- The widget receives a public site key and creates a token for the submission.
- 2. Your server
- It sends the token to /v1/verify. Optional fields such as message, name or email address are included only for the intended checks.
- 3. formconfirmed
- The API checks the token and signals and returns success, score, action and reasons, among other fields. AI checks can use a temporary internal queue.
- 4. Your application
- Your integration then decides from the response whether to process normally, explicitly hold for review or reject. An API response is not proof of delivery.
Compare integrations on their merits
Compare the actual API contract and the handling on your server.
- formconfirmed response
- /v1/verify provides a combined score, action and reasons. A similar API structure does not mean every field and decision is identical across providers.
- Check before switching
- Check the site key, server secret, token verification, error handling and handling of flag. Consult the target provider's current documentation.
- Compare allowances
- Compare only equally defined units and periods. A number alone does not establish greater coverage or better detection.
Example: registration spam
Registration spam using generated names on consented.eu prompted the existing demo example. It illustrates a pattern, not a success rate.
- Fictional example
- The demo uses a fictional, random-looking name. It creates no account and sends no confirmation email.
- Several signals
- An unusual name can contribute to the assessment. An unusual real name alone does not prove abuse.
- Handling in your application
- Read action before activating an account or sending an action email. flag needs handling that you have explicitly configured.
- Limits
- Compare with a legitimate registration. A demo result does not guarantee detection of every registration attack.
Two ways to get started
Start directly with the form or examine your website first.
- Protect a form directly
- Set up a site, embed the widget and verify the token on your server before processing. A plugin is available for WordPress.
- Start with a formexposed scan
- A website scan can help you find forms. This route is optional: it does not replace token verification in your application.
What your website needs
HTML and the widget run in the browser. Approval also requires server-side verification.
- Access to the integration
- You need to be able to change the form and its server-side processing, or configure a suitable plugin with the required permissions.
- Use keys correctly
- The site key is public. The secret stays on the server and belongs neither in HTML nor in browser JavaScript.
- Connection and response
- Your server must reach the Verify API and evaluate a valid response before processing a submission.
- Check the integration
- Test a normal submission, a flagged response and a technical failure. Verify actual handling in your application; a visible badge is not enough.
What does this example show?
You see the real result of this check, not a prepared sample result. It can differ from test to test, for example when the demo's AI allowance is used up or many tests come from the same network. Several signals decide together. The score is not proof that a person wrote the message.
- Genuine message
- A short, ordinary enquiry without a link. This is the normal case your form should let through. Sensible handling: With “allow”, your server processes the message as usual. Counter-check: Write an equally ordinary enquiry of your own and compare the result and the reasons.
- Link spam
- Only a list of links, no request. Link lists like this are a typical pattern of automatically distributed spam. A pre-filter for message texts is part of every plan. Sensible handling: With “block”, your server rejects the submission with a neutral message. With “flag”, it files it for review, for example in a spam folder. Counter-check: Choose “Genuine message with link”: a real request with a single link.
- Registration spam
- The registration example sends a fictional, random-looking name without a message. Browser and network signals are still checked. The demo creates no account and sends no email. Sensible handling: On your website: do not activate an account automatically. Depending on the action, refuse the registration or hold it for review. Counter-check: The other examples put an ordinary first name into the name field. Real names can look unusual, so if you moderate yourself, never refuse on the name alone.
- SEO spam
- An unsolicited offer of backlinks, unrelated to your website. What counts here is the content, not the number of links. Sensible handling: Flag it and put it into moderation or a spam folder, or reject it. Counter-check: Check a genuine enquiry on the same topic, for example: “We are looking for help with search engine optimisation. Could you send us an offer?” Compare the result.
- Phishing
- Time pressure (“now”, “lockout”), a request to enter a password and a link to a foreign address. The address ends in .example and cannot be reached. Sensible handling: Reject it or hold it for review. Do not forward it to staff unchecked. Counter-check: Check a genuine support question, for example: “I forgot my password. How can I reset it?”
- Genuine message with link
- A real request with a single link to project documents. The counterpart to link spam shows how a link is judged in context. Sensible handling: With “allow”, process it normally. With “flag”, file it for review and do not discard it silently. Counter-check: Choose “Link spam” and compare the reasons.