reCAPTCHA v3 and v3 Enterprise Solver API

reCAPTCHA v3 is the invisible version of Google reCAPTCHA. It shows no checkbox and no images: the script on the page watches how the visitor behaves and gives a score from 0.0 to 1.0, where 1.0 means "most likely a human". The site receives a token with this score and decides whether to let the request through.

Because there is nothing to click, reCAPTCHA v3 is solved with a token. You send the sitekey and the page URL to the Cap.guru API, get a ready token back and pass it to the site the same way the widget would. The corporate version, reCAPTCHA v3 Enterprise, is solved the same way with one extra parameter: see reCAPTCHA v3 Enterprise below.

You can see reCAPTCHA v3 in action on the reCAPTCHA demo page.

What you need

How to find the parameters (click to expand)

You need two values from the page with reCAPTCHA v3.

Page URL. The full address of the page where reCAPTCHA v3 runs, for example https://test.cap.guru/demo/recap.

Sitekey. Open the page, press F12 and look for the key in one of these places:

• the render parameter in the script link: https://www.google.com/recaptcha/api.js?render=6LdSQV8mAAAAAA8tgiox2isjB1H4QSr-pNBXajUT;
• a call like grecaptcha.execute('6LdSQV8mAAAAAA8tgiox2isjB1H4QSr-pNBXajUT', {action: 'submit'}) in the page scripts;
• the k parameter in the address of the reCAPTCHA iframe (Network tab, request to recaptcha/api2/anchor).

Action. In the same grecaptcha.execute call, look at the action value, for example {action: 'verify'} or {action: 'login'}. Some sites check that the token was issued for the right action, so pass it in the action parameter.

Take both values from the page where you actually pass the check, otherwise the token will fail validation.

Sending a task

http://api2.cap.guru/in.php

Optional parameters are sent only when you need them. If you do not use a parameter, leave it out of the request completely: do not send it empty or with a placeholder value.

Parameter	Type	Required	Description
key	String	Yes	Your API key. You can find it in the dashboard
method	String	Yes	userrecaptcha: tells the service that you are solving reCAPTCHA
googlekey	String	Yes	The sitekey you found on the page For example 6LdSQV8mAAAAAA8tgiox2isjB1H4QSr-pNBXajUT
pageurl	String	Yes	Full URL of the page with reCAPTCHA v3 For example https://test.cap.guru/demo/recap
version	String	Yes	v3: tells the service that this is reCAPTCHA v3
action	String	No	The action name from the grecaptcha.execute call on the page, for example verify, login or submit. Pass it if the site checks the action
enterprise	Number	No	1: the site uses reCAPTCHA v3 Enterprise. For regular reCAPTCHA v3, do not send this parameter at all. See reCAPTCHA v3 Enterprise
softguru	Number	No	ID of the software developer. Developers who have integrated their software with our service receive 1% of the cost of each such request
json	Number Default: 0	No	0: the server returns a plain text response 1: the server returns a JSON response

Request example:

http://api2.cap.guru/in.php?key=YOUR_APIKEY&method=userrecaptcha&version=v3&googlekey=6LdSQV8mAAAAAA8tgiox2isjB1H4QSr-pNBXajUT&pageurl=https://test.cap.guru/demo/recap

OR

Request and response example

Request example

POST http://api2.cap.guru/in.php
Host: api2.cap.guru
Content-Type: application/json

{
  "key": "YOUR_API_KEY",
  "method": "userrecaptcha",
  "version": "v3",
  "googlekey": "6LdSQV8mAAAAAA8tgiox2isjB1H4QSr-pNBXajUT",
  "pageurl": "https://test.cap.guru/demo/recap",
  "json": 1
}

If the request is successful, you receive OK|65787087 or {"status":1,"request":"65787087"}. If you did not get a task number, check the full list of possible errors.

Response example

{
  "status": 1,
  "request": "65787087"
}

Getting a response

http://api2.cap.guru/res.php

Parameter	Type	Required	Description
key	String	Yes	The key can be viewed here
action	String	Yes	get — get response
id	Number	Yes	ID of captcha returned by in.php.
json	Number By default: 0	No	0 — the server will return a response in plain text 1 — the server will return a response in JSON format

Request/response example

Request example

POST  http://api2.cap.guru/res.php
Host: api2.cap.guru
Content-Type: application/json

{
  "key": "YOUR_API_KEY",
  "action": "get",
  "id": "XXXXXXXXXXXXXXXXXX", // for example 65787087
  "json": 1
}

After sending the task to us, you should receive in response 'OK|03 AFY_a8W0B6yEBwfbmzp6OEUr...' or {"status":1,"request":"03 AFY_a8W0B6yEBwfbmzp6OEUr..."} if the request is successful. Please read the full list of possible errors in case you have not received a response.

Sample response

{
 "status":1,
 "request":"03AFY_a8W0B6yEBwfbmzp6OEUr4GYgdREy1DAFvvtyI6FUzf5qY_738XQ9lIFB7huVK9qia1f9z1GyGWRW3HVEzIGU5JrR-DY2xAkVvdH23lbpBqFAvH79Rr4Cs5dsxENk_zoTa1jn70ORvBVfBHA_Fb-s_kqQEpmaxSIwf0fe8FGJjhsBoygXnvrmCnBPTf5ua4LoYSi4f12XcZdyf5dBRYPq4pHBqk5Ic2cj8InwX9ima-v9UKA64ugnIiUNFOB_BCHJ1tieaB-td4_B4MC8gBCzPQwwO5I3IDDaT17JR3uIBKfc70w-2mtDnfPznyT4dHZapWtZizLkGs2BSUsfM4nR9OtjshuYB8lwJkSfz3ynaBYOCE7SBbtVHCsjGgO7YtSI-BArHxUcPQdFILmtnSCvPV5IWEF_NxurJ3QlUMkaNvC6kHCphZZoJXpt8Q5f-Uyi0-bhGd4wjtqRFglyzpn8lEmqkxF2ydlQO1Ketclutd-w5wuuxoDDHJE7d5msHPjXYtVvuFh8A2nyAU4i2I5KfcmdMd3F2g"
}

reCAPTCHA v3 Enterprise

reCAPTCHA Enterprise is the corporate version of reCAPTCHA for large websites. For the visitor it looks the same as regular v3, but it is loaded and checked through a different Google service, so a regular v3 token will not pass on such a site.

How to recognize it. Open the page code or the Network tab. The site uses reCAPTCHA v3 Enterprise if you see:

• the script https://www.google.com/recaptcha/enterprise.js?render=SITEKEY instead of api.js;
• calls to grecaptcha.enterprise.execute(...) instead of grecaptcha.execute(...);
• requests to recaptcha/enterprise/anchor and recaptcha/enterprise/reload.

How to solve it. Send the same parameters as for regular v3 and add enterprise=1. Send this parameter only for Enterprise: for regular reCAPTCHA v3, leave it out completely. Enterprise sites check the action especially often, so pass action as well.

http://api2.cap.guru/in.php?key=YOUR_APIKEY&method=userrecaptcha&version=v3&enterprise=1&action=verify&googlekey=SITEKEY&pageurl=https://example.com/login

Request example in JSON

{
  "key": "YOUR_API_KEY",
  "method": "userrecaptcha",
  "version": "v3",
  "enterprise": 1,
  "action": "verify",
  "googlekey": "SITEKEY",
  "pageurl": "https://example.com/login",
  "json": 1
}

The token is used the same way as a regular v3 token. On Enterprise sites it is usually sent in a request after grecaptcha.enterprise.execute, not in the g-recaptcha-response form field, so check the Network tab to see where the site puts it.

How to use the token

The token is passed to the site the same way the reCAPTCHA script would pass it. Depending on the site, this is one of the following:

• the hidden g-recaptcha-response field in the form;
• a field or parameter in the request that the site sends to its server after grecaptcha.execute;
• the callback function that the site passes to reCAPTCHA.

Look at the page scripts or the Network tab to see where the site puts the token. Request the token right before submitting: a reCAPTCHA token is valid for about two minutes and works for a single check.

Tips

• The site rejects the token. Check that the sitekey and the page URL come from the same page, that the token is used within two minutes, and that action matches the value from grecaptcha.execute.
• The site uses Enterprise. If the page loads enterprise.js, add enterprise=1, otherwise the token will not pass.
• Invisible reCAPTCHA v2 is not v3. If the page has size=invisible in the iframe address and no render= parameter in the script, it is invisible reCAPTCHA v2. Solve it as described on the reCAPTCHA v2 page.