CAPTCHA Result Validation

Here we explain how you call up and evaluate the CAPTCHA result in your backend from our server.

It is possible to retrieve the CAPTCHA verification result from our servers in any programming language using a simple REST API call. To make this process as easy as possible, we provide ready-made integrations for the most popular programming languages and frameworks. The source code for all provided integrations can also be found on Github. The API call is documented in detail here, so that individual integrations are possible.

When the CAPTCHA widget is completely solved, the CAPTCHA returns a so-called verification token. This is a simple text/string. It is available in a hidden input field called tc-verification-token and is also propagated by the trustcaptcha component with the captchaSolved JavaScript event. You can find out more about this in the CAPTCHA widget overview.

Send this token to your backend. For example, when the form containing the CAPTCHA is submitted, or independently via an API interface. With the help of the verification token, you can now retrieve the CAPTCHA verification result from our servers on the server side. Either via an API interface or with the help of one of our ready-made integrations.

The verification token returned by the TrustCaptcha widget is encoded in Base64.

eyJhcGlFbmRwb2ludCI6Imh0dHBzOi8vYXBpLmNhcHRjaGEudHJ1c3RjYXB0Y2hhLmNvbSIsInZlcmlmaWNhdGlvbklkIjoiMDdiMDE5MjItM2ZhYS00NjY3LWE0YTYtOTEwYTc2Y2I4YWI3IiwiZW5jcnlwdGVkQWNjZXNzVG9rZW4iOiJtQ2JCZldTS0V5bWQxYjN0cW5ycXZCYURZMER2TkgwK29acHlYdTdSN1pkTUNMcjhhU202TURlM2ltckVPTTVDaFZOeUkvbkFSUFJCalNvV1N1NnNMNVlpUjhlUXU4dDZ3eUVBVDNRc3NwQT0ifQ0=

When you decode the verification token, you get back a JSON object. This contains the apiEndpoint and the verificationId you need to fetch the verification result via the REST-API.

{
  "apiEndpoint": "https://api.trustcomponent.com",
  "verificationId": "07b01922-3faa-4667-a4a6-910a76cb8ab7",
  "encryptedAccessToken": "mCbBfWSKEymd1b3tqnrqvBaDY0DvNH0+oZpyXu7R7ZdMCLr8aSm6MDe3imrEOM5ChVNyI/nARPRBjSoWSu6sL5YiR8eQu8t6wyEAT3QsspA="
}

Overview of the properties of the token:

Below you will be explained how to retrieve the CAPTCHA verification result, what information it contains, and how you can work with it.

You can retrieve the verification result from our servers using the following URL.

curl -X GET "https://{apiEndpoint}/verifications/{verificationId}/assessments"      -H "Content-Type: application/json"      -H "tc-authorization: {secret-key}"

Overview of request properties:

The returned verification result looks like this:

{
  "captchaId": "cc2e2d5e-d1ef-4a7f-a7bd-dec5b37df47a",
  "verificationId": "cc2e2d5e-d1ef-4a7f-a7bd-dec5b37df47a",
  "verificationPassed": true,
  "score": 0.5,
  "reason": "CALCULATED",
  "mode": "STANDARD",
  "origin": "https://www.your-website.com/sub-page",
  "ipAddress": "2a01:123:33bb:1a1a:0:0:0:1",
  "deviceFamily": "Other",
  "operatingSystem": "Windows 10",
  "browser": "Chrome 119.0.0",
  "creationTimestamp": "2020-01-01T13:30:05.941",
  "releaseTimestamp": "2020-01-01T13:30:05.941",
  "retrievalTimestamp": "2020-01-01T13:30:05.941"
}

Overview of the result properties:

The CAPTCHA verification result contains two important pieces of information: verificationPassed and score. Based on this information, you can define your individual rules and determine how to proceed.

• verificationPassed: Provides information on whether the CAPTCHA has been completed and passed

• score: The bot score indicates how likely a request is to originate from a bot. The value always ranges between 0 and 1, and the higher the value, the higher the bot risk.

As a starting point for your individual CAPTCHA validation, we recommend checking whether verificationPassed is true and whether the bot score value is below 0.5.

if (!verificationResult.verificationPassed || verificationResult.score > 0.5) {
    console.log("Verification failed or bot score > 0.5 – possible automated request.");
} else {
    console.log("Everything looks good - probably a human.");
}

We recommend always checking expressions to see if verificationPassed is true. If you don’t want to check for bot probability but only the dynamic proof-of-work, you can skip the bot score check.

if (!verificationResult.verificationPassed) {
    console.log("Verification failed");
} else {
    console.log("Verification passed.");
}

The score threshold of 0.5 is not suitable for everyone. Everyone has different security needs or a higher tolerance for false positives detected as bots or spam messages. So experiment with the threshold value of 0.5 and adjust it to your individual needs. Note: 0 = probably human, 1 = probably bot/automated.

const threshold = 0.75; // allow more false positives
if (!verificationResult.verificationPassed || verificationResult.score > threshold) {
    console.log("Verification failed or bot score > "+threshold+" – possible automated request.");
} else {
    console.log("Everything looks good - probably a human.");
}

A multi-stage process is also possible. For example, you could take different approaches based on the score and thus based on individual risk. This means that a user does not have to be excluded immediately or a message blocked; instead, you could simply add an additional security check in the event of an increased risk.

if (!verificationResult.verificationPassed) {
  console.log("Captcha failed → reject.");
} else if (verificationResult.score >= 0.8) {
  console.log("High bot risk → reject.");
} else if (verificationResult.score >= 0.4) {
  console.log("Elevated risk → e.g. require email verification or 2FA.");
} else {
  console.log("Low risk → allow / proceed.");
}

The reason provides insight into why the bot score and the statement about verificationPassed were made accordingly.

Errors can occur when retrieving the “erification result`. Below you will find an overview of all status codes along with a description of what went wrong and what you should consider.