This document describes the technical integration, usage, and customisation options of the ZeroCaptcha abuse detection service.
ZeroCaptcha assesses the risk of abuse, spam, and use of anonymisers at the point of form submission. It operates completely invisibly with zero friction for the end-user, protecting websites and online platforms from malicious activity.
To integrate ZeroCaptcha, include the following JavaScript library in the HTML code of the webpage containing the form(s) you wish to protect:
<script type="text/javascript" src="https://api.zerocaptcha.com/v1/zc.js" defer></script>
We recommend including it within the <head> tags, as shown in the HTML example below:
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript" src="https://api.zerocaptcha.com/v1/zc.js" defer></script>
</head>
<body>
<form name="exampleForm" action="result.php" method="post">
<input type="text" name="input1">
<button type="submit">Submit</button>
</form>
</body>
</html>
To retrieve the risk assessment for form submissions, send a JSON-RPC 2.0 request to the ZeroCaptcha endpoint. This protocol-agnostic approach allows integration with any backend using standard JSON-RPC libraries.
Endpoint Details
URL: https://api.zerocaptcha.com/v1
HTTP Header: Include the X-Api-Key header with your API key (obtained from the API Keys page in the Admin Panel).
The request object must include the following parameters:
{
"jsonrpc":"2.0",
"method":"AssessFormSubmission",
"params":[
zc_submission_id [, form_name [, form_id]]
],
"id":request_object_id
}
where:
- zc_submission_id (string): The submission identifier included in a hidden form field (default field name: "zc_submission_id").
- form_name (string): The name of the form to be displayed in the Admin Panel’s statistics. This is an optional parameter. If omitted, the system will use the "name" attribute of the associated HTML form tag, if present.
- form_id (string): The id of the form to be displayed in the Admin Panel’s statistics. This is an optional parameter. If omitted, the system will use the "id" attribute of the associated HTML form tag, if present.
- request_object_id (string): A unique identifier for the request (normally automatically assigned by JSON-RPC libraries).
The response includes the following information:
{
"jsonrpc":"2.0",
"result":{
"zc_submission_id":"...",
"ip_address":"192.168.122.19",
"abuse_risk_level":"low",
"abuse_risk_score":35,
"spam_risk_level":"low",
"spam_risk_score":21,
"anonymisation_probability":"low",
"country":"United Kingdom of Great Britain and Northern Ireland",
"country_code":"GB",
"time_zone":"Europe/London"
},
"id":"b28a873cdfa46479"
}
where:
- zc_submission_id (string): Submission identifier included in the form submission.
- ip_address (string): Originating IP address of the form submitter.
- abuse_risk_level (string): Abuse risk level: 'very_low', 'low', 'medium', 'high' or 'very_high'.
- abuse_risk_score (integer): Numeric abuse probability indicator (0-100 scale), where higher values denote higher risk.
- spam_risk_level (string): Spam risk level: 'very_low', 'low', 'medium', 'high' or 'very_high'.
- spam_risk_score (integer): Numeric spam probability indicator (0-100 scale), where higher values denote higher risk.
- anonymisation_probability (string): Anonymisation probability of anonymiser, VPN, or proxy usage: 'low', 'medium', 'high' or 'unassessable'*.
- country (string): Full country name of form submitter derived from IP geolocation.
- country_code (string): ISO 3166-1 alpha-2 country code of form submitter.
- time_zone (string): Time zone of the form submitter.
* The 'unassessable' status is assigned when the workflow is disrupted or manipulated, making it impossible to assess the anonymisation probability.
PHP Implementation Example (using the JsonRpcRequest PHP library):
<?php
require_once 'JsonRpcRequest.php';
//Replace the value of $api_key with an API key obtained from the ZeroCaptcha Admin Panel
$api_key = '...';
$api_url = 'https://api.zerocaptcha.com/v1';
try {
$json_rpc_request = new JsonRpcRequest($api_url);
$json_rpc_request->call(
'AssessFormSubmission',
[$_REQUEST['zc_submission_id'] ?? null],
["X-Api-Key: $api_key"]
);
$response = $json_rpc_request->getDecodedResponseObject();
if ($response && isset($response->result)) {
echo "<pre>";
var_dump($response->result);
echo "</pre>";
} else if ($response && isset($response->error)) {
echo "<pre>";
var_dump($response->error);
echo "</pre>";
} else {
echo 'Error. cURL error message is: ' . $json_rpc_request->getCurlErrorMsg();
}
} catch (Throwable $t) {
echo $t->getMessage();
}
Important:
- Send the assessment request immediately after receiving the form submission (batch requests are not supported).
- Each submission identifier must be sent only once.
For JSON-RPC 2.0 libraries, refer to the Awesome JSON-RPC GitHub repository.
4.1. Selecting Specific Forms for Processing
By default, ZeroCaptcha processes all forms on the page. To restrict processing to specific forms use the
data-zerocaptcha-form-id or data-zerocaptcha-form-classname data attributes as follows:
4.1.1. Using "data-zerocaptcha-form-id"
Add the `data-zerocaptcha-form-id` attribute to the script tag, with the value being the ID of the form:
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript"
src="https://api.zerocaptcha.com/v1/zc.js"
data-zerocaptcha-form-id="exampleFormId"
defer>
</script>
</head>
<body>
<form id="exampleFormId" action="result.php" method="POST">
<input type="text" name="input1">
<button type="submit">Submit</button>
</form>
</body>
</html>
4.1.2. Using "data-zerocaptcha-form-classname"
Add the `data-zerocaptcha-form-classname` attribute to the script tag, with the value being the class name of the form(s):
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript"
src="https://api.zerocaptcha.com/v1/zc.js"
data-zerocaptcha-form-classname="my-form-class"
defer>
</script>
</head>
<body>
<form class="my-form-class" action="result.php" method="POST">
<input type="text" name="input1">
<button type="submit">Submit</button>
</form>
</body>
</html>
4.2. Changing the Submission Identifier Field Name
By default, ZeroCaptcha adds a hidden field named 'zc_submission_id'. To customise this field name, add the data-zerocaptcha-form-field attribute to the script tag:
<script type="text/javascript"
src="https://api.zerocaptcha.com/v1/zc.js"
data-zerocaptcha-form-field="example_form_field_name"
defer>
</script>
If you change the field name, your backend must pass the value of the same field name when submitting the submission identifier to the ZeroCaptcha endpoint.
For further details, consult the FAQs or contact our support team for detailed guidance.