Technical details of the backend

The following explains how to retrieve the verification result on the server side and determine the next steps based on it.

Supported Technologies

You can use Trustcaptcha with any programming language and framework of your choice and customize it entirely to your needs. Below you will find detailed documentation of the backend process and the corresponding API interface.

Library Support

To make it as easy as possible for you to use Trustcaptcha, you can use our libraries for the most popular programming languages and frameworks. You can find a guide to integration here.

The following technologies are currently supported by us:

Typescript

NodeJS

Python

Java

Kotlin

Spring

PHP

Ruby

.NET

Rust

Groovy

Scala

The Verification Token

When a captcha is successfully solved, the Trustcaptcha component returns a verification token. This must be transmitted to the backend and can be further processed there. Below, the structure of the verification token is explained.

Base64 Encoded

The verification token returned by the Trustcaptcha component is encoded in Base64.

Base64 Decoded

When you decode the verification token, you get back a JSON object. This contains the verification ID and and the API endpoint, where the verification result can be retrieved.

Key	Value	Description
apiEndpoint	Text	Endpoint where the verification result can be retrieved. As a rule https://api.captcha.trustcaptcha.com
verificationId	UUID	Unique identifier (ID) of the verification.
encryptedAccessToken	Text	Deprecated: Encrypted access token for retrieving the verification result.

The Verification Result

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

Retrieving the Result

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

Parameter	Type	Description
apiEndpoint	Path	Endpoint where the verification result can be retrieved. Can be taken from the verification token. As a rule https://api.captcha.trustcaptcha.com
verificationId	Path	Unique identifier (ID) of the verification. Can be taken from the verification token.
secret-key	Header	Secret key of the CAPTCHA. This can be taken from the CAPTCHA administration.

Please note that the verification token becomes invalid after 15 minutes and the verification result can only be received once.

Processing the Result

The returned verification result looks like this:

Parameter	Value	Description
captchaId	UUID	Unique identifier (ID) of the respective CAPTCHA.
verificationId	UUID	Unique identifier (ID) of the verification.
verificationPassed	Boolean	Statement on whether the CAPTCHA was fundamentally passed or not.
score	Number	Probability level that the client is a bot.
reason	Text	Rationale for calculating verificationPassed and score.
mode	Text	Selected captcha mode.
origin	Text	The page where the captcha was solved.
ipAddress	Text	IP address (IPv4 or IPv6) of the client.
deviceFamily	Text	Name of the device family used by the client.
operatingSystem	Text	Name and version of the operating system used by the client.
browser	Text	Name and version of the browser used by the client.
creationTimestamp	Timestamp (UTC)	The moment when the verification process (the CAPTCHA) was started by the client.
releaseTimestamp	Timestamp (UTC)	The moment when the verification process (the CAPTCHA) was completed by the client.
retrievalTimestamp	Timestamp (UTC)	The moment when the verification result was called up by the website operator.

The Bot Score

The Bot Score returns a decimal value between 0 and 1. It provides information on the likelihood that the requesting client is a bot. The lower the value, the more likely the user is human. The higher the value, the more likely it is a machine user.

The Bot Score allows you to define a simple threshold at which you either allow or deny the request. Our recommendation is to set the threshold at 0.5. However, based on the Bot Score, you can also establish different security measures for various probabilities, such as additional two-factor authentication or email confirmation.

The Reason

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

Reason	VerificationPassed	Score	Description
BYPASS_KEY	true	0	The captcha was solved using a bypass token.
CUSTOM_ALLOW_LIST	true	0	The client's IP address is on the custom allow list.
CUSTOM_BLOCK_LIST	false	1	The client's IP address is on the custom block list.
GLOBAL_ALLOW_LIST	true	0	The client's IP address is on Trustcaptcha's global allow list.
GLOBAL_BLOCK_LIST	false	1	The client's IP address is on Trustcaptcha's global block list.
GEOBLOCKING	false	1	The client's region is blocked on the country list.
REQUEST_REJECTED	false	1	The verification attempt was rejected by Trustcaptcha.
ONLY_PROOF_OF_WORK	true	0	Verification passed without bot-score (e.g. minimal data mode).
CALCULATED	true	Individual	The bot score was calculated based on data analysis.
CHALLENGES_NOT_SOLVED_CORRECTLY	false	1	The client did not correctly calculate the Proof-of-Work challenges.
CHALLENGES_NOT_SOLVED_IN_SPECIFIED_TIME	false	1	The client did not submit the Proof-of-Work challenges within the specified time.

Error Handling

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

Status Code	Status Name	Description
400	Bad Request	The request was made under false assumptions. Possibly the verification ID (verificationId) is not a UUID or the access token (accessToken) does not match the specified format.
403	Forbidden	The secret key in the header (old versions the access token as query parameter) is missing in the HTTP request or is invalid. Please check the request and access data.
404	Not Found	The verification does not exist. Please check the verification ID. It is also possible that the verification has already been retrieved and is now deleted.
410	Gone	The verification result has either already been retrieved or is no longer provided, as the verification attempt is too old. Remember that you can only retrieve the verification result once, shortly after the verification.
423	Locked	The verification result has not yet been released. Please wait until the verification is complete.
422	Unprocessable Content	The set captcha mode of the Trustcaptcha component does not match the set mode in the captcha settings.
500	Internal Server Error	An internal server error has occurred. If this happens repeatedly and persists over time, please contact support.