PRODUCT TEST WORKSPACE

reCAPTCHA v2 Enterprise

Captcha verification product

RECAPTCHA_V2_ENTERPRISE

01 / CREATE

Create task

The editor starts with required fields and one conditional branch. Optional fields are listed below and can be loaded into the editor.

02 / REQUEST

Request preview

POST /api/validator/create.cgi
{
  "productCode" : "RECAPTCHA_V2_ENTERPRISE",
  "adapter" : {
    "websiteURL" : "https://example.com/register",
    "websiteKey" : "YOUR_WEBSITEKEY"
  }
}

03 / RESULT

Response example

EXAMPLE
Task ID —
{
  "code" : 0,
  "msg" : "Success",
  "data" : {
    "taskId" : "11111111-1111-4111-8111-111111111111",
    "productCode" : "RECAPTCHA_V2_ENTERPRISE",
    "state" : "SUCCEEDED",
    "solution" : {
      "gRecaptchaResponse" : "EXAMPLE_GRECAPTCHARESPONSE",
      "token" : "EXAMPLE_TOKEN"
    }
  }
}

Illustrative response; not a live task result. Replace all request placeholders before submitting.

Read data.solution after state becomes SUCCEEDED. The solution fields depend on the product; other states may return an empty object.

04 / API REFERENCE

reCAPTCHA v2 Enterprise · API

For task creation and queries, send the API key in the apiKey HTTP header. JSON request bodies contain business parameters only.

Content-Type: application/json
apiKey: YOUR_API_KEY

Request example

POST /api/validator/create.cgi · JSONC
{
  "productCode": "RECAPTCHA_V2_ENTERPRISE", // Product code matching the adapter parameters.
  "adapter": { // Product-specific parameter object.
    "websiteURL": "https://example.com/register", // Read from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
    "websiteKey": "YOUR_WEBSITEKEY", // Read from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
    "pageAction": "YOUR_PAGEACTION", // Actual v3 action from the target execute options. This legacy field remains accepted for v2 compatibility, but it does not replace data-s or enterprisePayload.s and does not select the product version.
    "apiDomain": "YOUR_APIDOMAIN", // Read from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
    "isEnterprise": false, // For RECAPTCHA_V3_ENTERPRISE the upstream flag is always true, including legacy requests that send false. RECAPTCHA_V3 keeps its existing optional flag behavior. Select the explicit v2 Enterprise product for Enterprise widgets; this flag cannot supply missing session parameters.
    "minScore": 0.3, // Set according to the actual challenge and product field meaning. These are solving options, not values to invent to repair a failed request.
    "userAgent": "YOUR_BROWSER_USER_AGENT", // Read the actual User-Agent used to obtain this challenge; preserve it when the product requires matching.
    "isInvisible": false, // Read from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
    "cookies": "challenge_cookie=CURRENT_VALUE", // Optional current challenge cookie-header string for v2/v2 Enterprise, formatted key=value; key2=value2. Collect from the relevant target context; omit when not needed. This field is not exposed for v3.
    "proxyType": "http", // Optional v2/v2 Enterprise proxy protocol: http, socks4 or socks5. Any proxy field requires proxyType, proxyAddress and proxyPort together; omit all to retain proxyless mode. v3 has no documented proxy task here.
    "proxyAddress": "YOUR_PROXY_HOST", // Reachable proxy hostname or IP, without scheme, port or credentials. When target IP binding is required, the solver and target browser must use the same actual egress; setting a browser proxy alone is insufficient.
    "proxyPort": 8080, // Proxy TCP port, integer 1 to 65535; required only when any proxy parameter is supplied.
    "proxyLogin": "YOUR_PROXYLOGIN", // Optional proxy authentication username from the caller configured proxy; never invent credentials.
    "proxyPassword": "YOUR_PROXYPASSWORD", // Optional proxy authentication password from the same configured proxy.
    "enterprisePayload": { // Optional JSON object of additional parameters from the current grecaptcha.enterprise.render configuration, including its s string when present. Preserve this object with the matching challenge; do not send recaptchaDataSValue for Enterprise v2. Not a documented v3 field.
      "s": "CURRENT_ENTERPRISE_S_VALUE"
    }
  }
}

Request headers: apiKey: YOUR_API_KEY

Comments explain the fields. Copy produces valid JSON without comments.

Response example

POST /api/validator/query.cgi · JSONC
{
  "code": 0, // Business result code: 0 means success; other values indicate an error.
  "msg": "Success", // Result message; may be empty on success.
  "data": { // Response data; may be null on an error.
    "taskId": "11111111-1111-4111-8111-111111111111", // Task ID returned by task creation.
    "productCode": "RECAPTCHA_V2_ENTERPRISE", // Product code matching the adapter parameters.
    "state": "SUCCEEDED", // Task state: CREATED, SUBMITTING, PROCESSING, SUCCEEDED, FAILED or EXPIRED.
    "solution": { // Product answer when SUCCEEDED; empty while processing or on failure.
      "gRecaptchaResponse": "EXAMPLE_GRECAPTCHARESPONSE", // Verification token to submit to the target website.
      "token": "EXAMPLE_TOKEN" // Verification token to submit to the target website.
    }
  }
}

Creating a task returns its ID and initial state. Query the result or use WebSocket to receive the completed answer shown below.

Request parameters

FieldTypeRequiredDescription
productCodestringYesProduct code matching the adapter parameters.
adapterobjectYesProduct-specific parameter object.
adapter.websiteURLstringYesRead from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
adapter.websiteKeystringYesRead from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
adapter.pageActionstringNoActual v3 action from the target execute options. This legacy field remains accepted for v2 compatibility, but it does not replace data-s or enterprisePayload.s and does not select the product version.
adapter.apiDomainstringNoRead from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
adapter.isEnterprisebooleanNoFor RECAPTCHA_V3_ENTERPRISE the upstream flag is always true, including legacy requests that send false. RECAPTCHA_V3 keeps its existing optional flag behavior. Select the explicit v2 Enterprise product for Enterprise widgets; this flag cannot supply missing session parameters.
adapter.minScorenumberNoSet according to the actual challenge and product field meaning. These are solving options, not values to invent to repair a failed request.
adapter.userAgentstringNoRead the actual User-Agent used to obtain this challenge; preserve it when the product requires matching.
adapter.isInvisiblebooleanNoRead from the actual target page, widget configuration or documented integration. Identify the precise product/version; placeholders and keys from another site cannot be substituted.
adapter.cookiesstringNoOptional current challenge cookie-header string for v2/v2 Enterprise, formatted key=value; key2=value2. Collect from the relevant target context; omit when not needed. This field is not exposed for v3.
adapter.proxyTypestringNoOptional v2/v2 Enterprise proxy protocol: http, socks4 or socks5. Any proxy field requires proxyType, proxyAddress and proxyPort together; omit all to retain proxyless mode. v3 has no documented proxy task here.
adapter.proxyAddressstringNoReachable proxy hostname or IP, without scheme, port or credentials. When target IP binding is required, the solver and target browser must use the same actual egress; setting a browser proxy alone is insufficient.
adapter.proxyPortintegerNoProxy TCP port, integer 1 to 65535; required only when any proxy parameter is supplied.
adapter.proxyLoginstringNoOptional proxy authentication username from the caller configured proxy; never invent credentials.
adapter.proxyPasswordstringNoOptional proxy authentication password from the same configured proxy.
adapter.enterprisePayloadobjectNoOptional JSON object of additional parameters from the current grecaptcha.enterprise.render configuration, including its s string when present. Preserve this object with the matching challenge; do not send recaptchaDataSValue for Enterprise v2. Not a documented v3 field.

Response parameters

FieldTypeDescription
codeintegerBusiness result code: 0 means success; other values indicate an error.
msgstringResult message; may be empty on success.
dataobject | nullResponse data; may be null on an error.
data.taskIdstringTask ID returned by task creation.
data.productCodestringProduct code matching the adapter parameters.
data.statestringTask state: CREATED, SUBMITTING, PROCESSING, SUCCEEDED, FAILED or EXPIRED.
data.solutionobjectProduct answer when SUCCEEDED; empty while processing or on failure.
data.failureobject | omittedPublic diagnosis for FAILED/EXPIRED only; no raw provider messages. Follow the failure handling guide.
data.failure.codestringFailure code
data.failure.nextActionstringNext action
data.solution.gRecaptchaResponsestringVerification token to submit to the target website.
data.solution.tokenstringVerification token to submit to the target website.

Responses

HTTP business responses contain code, msg and data; code 0 means success. WebSocket uses a separate message structure.

-1317
Invalid API key.
-1100 / -1101
Invalid or missing request parameters.
-1401
Insufficient balance. Add funds before creating a task.
-1400 / -1001
System or task creation error.
API documentation