For developers

Small integration.
Useful protection.

Add human checks to your forms, or check submitted content with the spam API.

Check a submission

curl https://api.defendium.com/check \
  --data-urlencode 'secret_key=YOUR_ACCOUNT_KEY' \
  --data-urlencode 'content=The submitted comment' \
  --data-urlencode 'url=https://example.com/post' \
  --data-urlencode 'ip=203.0.113.10'

{"result": false}

true means spam; false means allowed. JSON and form-encoded POST bodies are accepted. GET remains available for existing integrations. Keep keys on your server.

Parameters

secret_keyRequired account secret

contentRequired; up to 100 KB

url, ip, user_agentSubmission context

referrer, authorSource and author

author_email, author_urlAuthor details

content_type, languages, charsetContent metadata

Human checks

One script. A verdict on your server.

Defendium handles background proof of work and any required confirmation. Your application only needs to check the submitted token before accepting a protected action. Human checks require no API key or site key.

1. Enable your site

Add and verify your domain under Sites, then enable invisible human checks. Add this script once to your page layout. If you already use it for analytics, keep the existing tag.

<script src="https://defendium.com/protect.js" async></script>

Defendium loads the human-check script only for opted-in, verified sites. It automatically adds a hidden _defendium token to same-origin forms that change data, including dynamically added forms. GET forms and forms submitting to other origins are excluded.

Only specific pages? Skip the site setup and add the human-check script to just those pages. Any domain can use it without signing up:

<script src="https://defendium.com/human.js" async></script>

Then send "required":true in step 2 from the actions those pages submit to.

2. Check the token on your server

Read _defendium from the submitted form. Before saving or performing the action, send it to Defendium with your website's hostname. Use your configured hostname, not a domain supplied in the submitted form.

curl https://defendium.com/human/verify \
  -H 'Content-Type: application/json' \
  --data '{"token":"SUBMITTED_DEFENDIUM_TOKEN","host":"example.com"}'

{"result":"pass"}

A completed check returns {"result":"pass"}, or {"result":"spam"} when a recent comment-spammer listing and a threat score above 30 still warrant blocking it. Both verdicts finalize the token. Missing, pending, expired, wrong-host, or previously finalized tokens return {"result":"fail"}. A host without invisible human checks turned on returns {"result":"unavailable"} whatever the token, because its pages are never given one; send the check even when the form token is missing, and the answer tells you whether the site is protected. Add "required":true when the action's page loads human.js itself: the host setting is then skipped, so a missing token fails instead of returning unavailable. Accept the protected action only after a pass; block both fail and spam.

Check once per request and reuse that result if multiple validations need it: a second check of a consumed token will fail. Network failures and HTTP 503 mean the service is unavailable; choose an explicit outage policy instead of treating an error as a pass. For protection that fails closed, preserve the submitted data and offer a retry.

Tokens exist immediately and become approved as the browser finishes the required steps. Defendium does not delay, cancel, or resubmit forms. If someone submits too early, keep their input and let them finish the check and try again. The browser script refreshes consumed tokens after normal form activity.

3. Optional placement and callbacks

When confirmation is needed, the button appears above the likely submit action. A centered dialog is used when a suitable submit control cannot be found. To choose the location yourself, add a container and reference it on the original script tag:

<div id="human-check"></div>
<script src="https://defendium.com/protect.js" async
        data-defendium-placement="#human-check"></script>

To exclude an individual form from automatic token insertion, add data-defendium="off" to that form. For custom fetch or JSON submissions, include the token returned by window.Defendium?.human?.getToken() in your request and check it on the server using the same endpoint.

document.addEventListener('defendium:human:approved', function () {
  // Optional UI feedback. Still check the token on your server.
});

Other events include ready, progress, challenge, expired, and error, each with the defendium:human: prefix. Register listeners before the script loads if you need the initial events. After a custom submission, call window.Defendium?.human?.refresh() to prepare another token.

Try every stage

Visit /harden from the same connection as your test browser. Pick a minimum level for ten minutes, switch levels, or select the current level to reset the checks and repeat them. Return to your form and reload it. Reputation and traffic requirements still apply.

Visitors can read what the human check is and why it appears through the small Defendium link on the confirmation panel.