reCAPTCHA API Documentation

reCAPTCHA is a freely available CAPTCHA implementation. It distinguishes humans from computers. This may be useful for:

A registration page for a forum or wiki.
A comment form.
Hiding information that could be useful to spammers (we recommend the reCAPTCHA Mailhide API for this).

How the reCAPTCHA API Works

API diagram

The user loads the web page with the reCAPTCHA challenge JavaScript embedded.
The user's browser requests a challenge from reCAPTCHA. reCAPTCHA gives the user a challenge and a token that identifies the challenge.
The user fills out the web page form, and submits the result to your application server, along with the challenge token.
reCAPTCHA checks the user's answer, and gives you back a response.
If true, generally you will allow the user access to some service or information. E.g. allow them to comment on a forum, register for a wiki, or get access to an email address. If false, you can allow the user to try again.

This document describes the validation steps in the process. Our Client API is used to embed the reCAPTCHA on your website.

Signing up for a reCAPTCHA Key

In order to use reCAPTCHA, you need a public/private API key pair. This key pair helps to prevent an attack where somebody hosts a reCAPTCHA on their website, collects answers from their visitors and submits the answers to your site. You can sign up for a key on the reCAPTCHA Administration Portal.

Key Scope

Your reCAPTCHA token is valid only at the domain you sign up for and any subdomains (due to the potential attack mentioned above). Some users require keys for multiple sites, for example, a development server and a production server or simply multiple sites hosted on the same server. Three techniques can be used to work around this:

If one of your servers is "localhost" or "127.0.0.1", reCAPTCHA will not enforce the same-domain rule. Just use the same key as for the production server.
Generate a key for a broader scope. For example, if your application is a.example.com and your test server is test.corp.example.com, generate a key for example.com.
Generate a different key for each domain.

Getting a reCAPTCHA Challenge

Your application will need to display a reCAPTCHA challenge on your web page. This can be done with the Client API, a piece of JavaScript code which lets you embed the CAPTCHA on your website.

Verifying the reCAPTCHA Solution

URL http://api-verify.recaptcha.net/verify

Parameters (sent via POST)

privatekey (required) Your private key

remoteip (required) The IP address of the user who solved the CAPTCHA.

challenge (required) The value of "recaptcha_challenge_field" sent via the form

response (required) The value of "recaptcha_response_field" sent via the form

Response The response from verify is a series of strings separated by \n. To read the string, split the line and read each field. New lines may be added in the future. Implementations should ignore these lines

Line 1 "true" or "false". True if the reCAPTCHA was successful

Line 2 if Line 1 is false, then this string will be an error code. reCAPTCHA can display the error to the user (through the error parameter of api.recaptcha.net/challenge). Implementations should not depend on error code names, as they may change in the future.

Example: If your response looks like this:

false
incorrect-captcha-sol

... you can add '&error=incorrect-captcha-sol' to the challenge request URL, and the user will get an error code.

Error Code Reference

reCAPTCHA currently returns the following error codes. Note that these codes should not be programmed for specifically as the are subject to change.

unknown Unknown error.

invalid-site-public-key We weren't able to verify the public key.
Possible Solutions

Did you swap the public and private key? It is important to use the correct one

Did you make sure to copy the entire key, with all hyphens and underscores, but without any spaces? The key should be exactly 40 letters long.

invalid-site-private-key We weren't able to verify the private key.
Possible Solutions

Did you swap the public and private key? It is important to use the correct one

Did you make sure to copy the entire key, with all hyphens and underscores, but without any spaces? The key should be exactly 40 letters long.

invalid-request-cookie The challenge parameter of the verify script was incorrect.

incorrect-captcha-sol The CAPTCHA solution was incorrect.

verify-params-incorrect The parameters to /verify were incorrect, make sure you are passing all the required parameters.

invalid-referrer reCAPTCHA API keys are tied to a specific domain name for security reasons. See above for tips on this matter.

recaptcha-not-reachable reCAPTCHA never returns this error code. A plugin should manually return this code in the unlikely event that it is unable to contact the reCAPTCHA verify server.

Tips & Guidelines

If the value of "recaptcha_challenge_field" or "recaptcha_response_field" is not set, avoid sending a request to api-verify.recaptcha.net. This allows you to more quickly deal with simple attempts at spamming.
If you are writing a plugin for an application, you can link to http://recaptcha.net/api/getkey to offer the user a chance to create a key. This url has two optional parameters, "domain" which will pre-fill the domain field of the sign-up page and "app" which can be the name of the plugin you are writing (this lets us track which plugins are popular).

That's it. You might want to look at the resources page to see examples of how to use reCAPTCHA in applications.

Other Resources

The reCAPTCHA Discussion Group, where you can discuss the reCAPTCHA API with other users as well as the developers of reCAPTCHA.
reCAPTCHA Resources Index. Links to plugins and libraries.
The reCAPTCHA Plugins & Libraries Project, where you can find plugins for various applications and reCAPTCHA helper libraries.