API integration example
This page shows the normal check flow, the trigger verification step, and how Admin-managed multi-site plus multi-endpoint Turnstile action mapping works.
1) Initial check
Call /api/v1/check from your posting application before saving the form or sending mail.
POST /api/v1/check
{
"site_id": "main-site",
"endpoint": "contact_form",
"client_ip": "203.0.113.10",
"user_agent": "Mozilla/5.0",
"email": "person@example.com",
"cookie_id": "browser-123",
"payload_hash": "sha256-of-form-payload",
"js_passed": true
}
Use site_id to identify the application or site, and endpoint to identify the protected function, such as contact_form, newsletter_signup, or job_apply.
2) If decision is TRIGGER
After your challenge completes, call /api/v1/verify-trigger.
POST /api/v1/verify-trigger
{
"site_id": "main-site",
"endpoint": "contact_form",
"turnstile_token": "token-from-cloudflare-turnstile"
}
For local testing in the bundled Posting App, you can also send challenge_response = let-me-in to simulate a successful verification without requiring Turnstile.
3) Site Turnstile Overrides in Admin
In Admin > Sites, each site can define endpoint-to-action mappings using one line per entry.
contact_form=contact_form newsletter_signup=newsletter_signup job_apply=job_apply
Recommended: keep the endpoint and action the same. Only use different values when your frontend action names differ from your SITIX endpoint names.
4) PHP server-side example
Your application endpoint can call SITIX before doing the real work.
$payload = [
'site_id' => 'main-site',
'endpoint' => 'contact_form',
'client_ip' => $_SERVER['REMOTE_ADDR'] ?? '',
'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? '',
'email' => $_POST['email'] ?? '',
'cookie_id' => $_COOKIE['sitix_browser_id'] ?? '',
'payload_hash' => hash('sha256', 'normalized-form-data'),
'js_passed' => true,
];
Full working examples are included in docs/posting_app_endpoint_example.php and docs/posting_app_verify_trigger_example.php.
Decision handling guide
if decision == PASS:
proceed with real submit, include decision_token
elif decision == TRIGGER:
render Turnstile or your challenge UI
then call /api/v1/verify-trigger
else:
stop and show retry-later message