formconfirmedSign inStart free

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).

FieldMeaning
secretrequiredYour secret key (fcp_sec_…). Never put it in the page.
responserequiredThe token from the form field fcp-response. Send it even if it is empty – do not reject a missing token yourself.
remoteipoptionalIP address of the visitor. Sharpens rate and network signals.
contentoptionalMessage 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.
emailoptionalE-mail address from the form: disposable providers and domains without mail are recognised.
nameoptionalName 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.
hpoptionalValue of the hidden field fcp-website (honeypot).
expected_purposeoptionalThe purpose the widget was signed for, e.g. contact, login, register. A token for another purpose is rejected.
operation_idoptionalStable ID of the business action (16–128 characters) – repeated requests do not count twice. Only together with expected_purpose.
recipientoptionalRecipient of an action mail (e.g. password reset) for the per-recipient limits.
form_modeoptionalinteractive (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" }
successtrue only if the action is allow; false for flag, block or an invalid request.
scoreCombined assessment from 0.0 (many suspicious signals) to 1.0 (no suspicious signals detected). This is not proof that a visitor is human.
actionallow, flag or block – the recommended handling.
reasonsSignals that led to the result, e.g. too_fast, honeypot_filled.
error-codesTechnical errors, see below.
challenge_tsTime the task was solved (UTC).
hostnameHost on which the widget ran.
contentOnly with content check: category and confidence.
support_idOpaque 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

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-secretNo secret key sent.
invalid-input-secretUnknown or revoked secret key.
missing-input-responseNo token sent.
invalid-input-responseToken invalid, expired or already used.
purpose-mismatchThe token was issued for another purpose.
purpose-not-allowedThis purpose is not allowed for the site (dashboard setting).
site-pausedThe site is paused in the dashboard.
service-disabledThe service is switched off temporarily.
bad-requestFields missing, too long or in the wrong format.
service-unavailableThe 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

  1. 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”.
  2. Open Settings → formconfirmed → “Settings” and choose “Connect with formconfirmed”.
  3. Open your formconfirmed account, compare the website and request code and approve the connection.
  4. Return to WordPress and complete the connection.
  5. 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.
  6. As a visitor, open one of your protected forms, check for the formconfirmed badge and send a harmless test message. Check that it arrives.
  7. In the plugin, check that “Overview” shows a recent response. Marked submissions are listed under “Held messages”.

Open account

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.

Contact Form 7 · WPForms

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.