Integration Guides

Language-specific SDKs and examples for server-side verification.

Frontend (All Platforms)

Add this script tag to any page with a form you want to protect:

			<form action="/submit" method="POST">
  <input name="name" required>
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>

<script src="https://api.captchaoculto.com/client.js"
  data-co-site-key="YOUR_SITE_KEY" defer></script>
		

The script automatically protects all forms on the page. No additional frontend code needed.

Install

Copy CaptchaOculto.php to your project. No Composer required.

// Download from:
// https://github.com/captchaoculto/integrations/php/CaptchaOculto.php
require_once 'CaptchaOculto.php';

Usage

<?php
require_once 'CaptchaOculto.php';
$co = new CaptchaOculto('YOUR_API_KEY');

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $result = $co->verify($_POST['_co_verdict'] ?? '');

    if ($result->isBot()) {
        // Phantom success: bot thinks it worked
        echo json_encode(['success' => true]);
        exit;
    }

    if ($result->isSuspicious()) {
        // Flag for manual review
        processForm($_POST, $flagged = true);
    } else {
        // Human - process normally
        processForm($_POST);
    }
}
?>

Available Methods

$result->isHuman()        // score 0-25
$result->isSuspicious()   // score 26-50
$result->isBot()          // score 51-100
$result->shouldProcess()  // true if human or suspicious
$result->getScore()       // integer 0-100
$result->getClassification()  // "human", "suspicious", "bot"

Install

npm install captcha-oculto
// or copy node/index.js to your project

Express.js Middleware

const CaptchaOculto = require('captcha-oculto');
const co = new CaptchaOculto('YOUR_API_KEY');

// As middleware
app.post('/contact', co.middleware(), (req, res) => {
    if (req.captchaOculto.isBot) {
        return res.json({ success: true }); // Phantom success
    }
    // Process form...
    res.json({ success: true });
});

Manual Verification

const co = new CaptchaOculto('YOUR_API_KEY');

app.post('/submit', async (req, res) => {
    const result = await co.verify(req.body._co_verdict);

    if (result.isBot()) {
        return res.json({ success: true }); // Phantom
    }

    // result.getScore()          // 0-100
    // result.getClassification() // "human"|"suspicious"|"bot"
    // result.isHuman()           // boolean
    // result.isSuspicious()      // boolean

    // Process normally
});

Install

Upload captcha-oculto.php to your wp-content/plugins/ directory and activate.

Configuration

// In wp-config.php or via Settings > CAPTCHA Oculto
define('CAPTCHA_OCULTO_SITE_KEY', 'sk_your_site_key');
define('CAPTCHA_OCULTO_API_KEY', 'ak_your_api_key');

Features

The WordPress plugin automatically protects:

// - Login forms
// - Registration forms
// - Comment forms
// - Contact Form 7 (if installed)
// - WooCommerce checkout (if installed)
//
// No additional configuration needed.

Any Language - HTTP Request

You can verify from any language that can make HTTP requests.

Request

POST https://api.captchaoculto.com/verify
Content-Type: application/json

{
  "token": "THE_VERDICT_TOKEN_FROM_FORM",
  "api_key": "YOUR_API_KEY"
}

Response (Success)

{
  "valid": true,
  "score": 12,
  "classification": "human",
  "threshold": 50,
  "session_id": "co_abc123..."
}

Response (Bot Detected)

{
  "valid": true,
  "score": 85,
  "classification": "bot",
  "threshold": 50,
  "session_id": "co_xyz789..."
}

Python Example

import requests

verdict = request.form.get('_co_verdict', '')
resp = requests.post('https://api.captchaoculto.com/verify', json={
    'token': verdict,
    'api_key': 'YOUR_API_KEY'
})
result = resp.json()

if result.get('classification') == 'bot':
    return {'success': True}  # Phantom success

# Process normally