HelloCaptcha service API

Requests

• The functions of the service are done by the unique URL of each function.
• The URLs are defined in the HelloCaptcha.class.php file.
• The parameters passed to the service are passed in CGI variables.

Results

• The answer of a HelloCaptcha service function is a JSON encoded associative array. The array consitsts of two parts: data and exception. The data part contains the result of a function. The exception part contains the accidentally occurred exception.
• The advantage of this method is that the client library can throw the exception on the other side. This way the error handling can traverse between the servers. A custom client library can handle the error in a different way.
• The data part is the return result of the function. The type of the result is described at the documentation of the functions.

The functions of HelloCaptcha service

getNewTest

1. Description – This function should be called if someone needs a new CAPTCHA. By calling this method the HelloCaptcha server selects a test from the test pool and returns information for displaying a CAPTCHA.
2. Parameters
   1. profileid – The id of the HelloCaptcha profile to display. A profile id can be created by registering on www.hellocaptcha.com, and creating a profile on the admin menu.
3. Exceptions
   1. Throws an exception if
      1. The profile named profileid does not exist.
      2. There is no pre-rendered CAPTCHA in the profile pool, yet. Please wait, until HelloCaptcha server generates the CAPTCHA animations.
4. Result
   1. turingtestid – The id of the Turing test. When verifying the answer of the website visitor, this id must be passed to the HelloCaptcha server, in order to know to what to match against the answer.
   2. html – The HTML code for a standard HelloCaptcha box. The HTML code is provided by HelloCaptcha server. This way we can easily upgrade the visualization. Using this code is not necessary. Anyone can create a custom CAPTCHA box by using the information returned by this function.
   3. profile_technology – Defines the technology the CAPTCHA uses for displaying itself. HelloCaptcha uses animated GIF images. If the technology is animated GIF, then this value contains: “animated gif”. This variable is for later extension.
   4. profile_details – This key contains an associative array. The array holds the details of the profile.
   5. The animated gif case:
      1. image_src – The URL to the image of the CAPTCHA. The URL points to an animated GIF.
      2. image_width – The width of the image.
      3. image_height – The height of the image.

verifyAnswer

1. Description – The answer of a visitor can be checked by using this function.
2. Parameters
   1. turingtestid – The id of the Turing test. An id can be created using getNewTest function.
   2. answer – The answer for the CAPTCHA that needs to be verified.
3. Exceptions
   1. Throws an exception if
      1. The Turing test identified by turingtestid does not exist.
      2. Either test turingtestid or answer is empty.
      3. The Turing test was already verified once.
      4. The Turing test is expired.
      5. There are too many bad tries (on a retryable CAPTCHA).
4. Result
   1. is_valid – A boolean value specifying whether the answer is right.