Truform Captcha

Web integration

Embed the Truform widget with automatic or programmatic rendering.

For WordPress, Laravel, and copy-paste HTML starters, see Official integrations. The guide below covers manual embed options for any stack.

Script loader

Include the Syndaq-hosted loader once per page:

<script src="https://syndaq.com/truform/api.js" async defer></script>

The loader pulls widget assets from syndaq.com/truform/assets/ and sends challenge and verify requests to api.syndaq.com/v1/truform/.

Automatic rendering

Add a container with class truform and your public site key:

<div class="truform" data-sitekey="tf_pub_your_site_key"></div>

When the DOM is ready, the loader renders every matching element that does not already have a widget attached.

Optional data attributes

Attribute	Values	Description
`data-theme`	`light`, `dark`	Widget color theme (default: `light`)
`data-size`	`normal`, `compact`	Widget size (default: `normal`)
`data-puzzle-type`	puzzle type or `random`	Force a puzzle style (default: `random`)
`data-mode`	`interactive`, `managed`	Verification mode (default: `interactive`). Managed requires the matching site key setting in the client area
`data-callback`	function name on `window`	Called when the user completes the puzzle
`data-action`	string	Labels the verification (for example `login`, `checkout`). Echoed on siteverify when matched
`data-execute-on-submit`	`true`	Defer the puzzle until the parent form is submitted
`data-expired-callback`	function name	Called when verification fails or expires
`data-error-callback`	function name	Called on verify errors

Example with action tagging and submit trigger:

<form method="post" action="/contact">
  <div
    class="truform"
    data-sitekey="tf_pub_your_site_key"
    data-action="contact"
    data-execute-on-submit="true"
  ></div>
  <button type="submit">Send</button>
</form>

<div
  class="truform"
  data-sitekey="tf_pub_your_site_key"
  data-theme="dark"
  data-size="compact"
  data-callback="onTruformComplete"
></div>

<script>
  function onTruformComplete() {
    console.log('Puzzle completed');
  }
</script>

Programmatic API

The loader exposes a global truform object:

truform.render('#my-captcha', {
  sitekey: 'tf_pub_your_site_key',
  theme: 'light',
  size: 'normal',
  callback: function () {
    console.log('done');
  },
});

Methods

Method	Description
`truform.render(container, options)`	Render into a selector or DOM element. Returns a Promise that resolves to a widget id.
`truform.getResponse(widgetId?)`	Read the response token from a widget (or the first widget if id omitted).
`truform.reset(widgetId?)`	Reset one widget or all widgets.
`truform.ready(callback)`	Run a callback when the API is available.

Form submission

Truform adds a hidden input named truform-response containing the token. Read it on the client or let your form POST include it automatically:

document.querySelector('form').addEventListener('submit', function (event) {
  var token = truform.getResponse();
  if (!token) {
    event.preventDefault();
    alert('Please complete the verification.');
  }
});

Send the token to your backend and verify it with server verification before trusting the submission.

Managed verification (optional)

Managed mode is available on Developer and Enterprise plans. Most legitimate visitors verify without opening a puzzle. When risk signals require it, the widget automatically falls back to the standard interactive flow.

Managed mode is opt in. Existing embeds without data-mode="managed" continue to use Interactive verification.

Enable Managed mode

In the Syndaq client area, open Services → Truform → Manage on the site key.
Under Security and behavior, set Verification mode to Managed and save.
Replace your embed snippet with the one shown on the Integrate tab.

<script src="https://syndaq.com/truform/api.js" async defer data-cfasync="false"></script>
<div class="truform" data-sitekey="tf_pub_your_site_key" data-mode="managed"></div>

Behavior

On checkbox click (or form submit when data-execute-on-submit="true"), the widget calls POST /v1/truform/managed.
On success, the hidden truform-response field is filled the same way as after a puzzle.
If the API returns interactive_required, the widget loads a puzzle automatically.
Server-side validation is unchanged — call siteverify with your secret key as usual.

Programmatic example:

truform.render('#my-captcha', {
  sitekey: 'tf_pub_your_site_key',
  mode: 'managed',
  action: 'login',
});

See Release notes for version history and upgrade notes.

Each site key only works on its configured domain and subdomains. See Site keys and security if the widget fails to load on a new hostname.