reCAPTCHA Enterprise API integration guide

A reCAPTCHA Enterprise API integration needs a task type that matches the enterprise widget, a server-side request path, and a deliberate handoff for the returned token. CapBypass currently lists ReCaptchaV3EnterpriseTaskProxyLess as active. This guide uses that exact task type for authorized automation on a site you control or are permitted to test.

The integration has two HTTP operations. Send the page URL and site key to createTask, then poll getTaskResult with the returned task ID. When the result status becomes ready, read solution.gRecaptchaResponse and submit that token only to the authorized page and action that requested it.

reCAPTCHA Enterprise API request checklist

The current reCAPTCHA v3 documentation identifies ReCaptchaV3EnterpriseTaskProxyLess as the proxyless type for Enterprise v3. Its documented required task fields are type, websiteURL, and websiteKey. pageAction is optional and should be included when the page calls grecaptcha.enterprise.execute() with an action. The same documentation also lists enterprisePayload as an optional object for extra options passed to that Enterprise execute call.

Start by inspecting the application you are authorized to automate. Record the page URL exactly as loaded and the public site key used by the widget. If the integration supplies an action, use the same action string. Do not treat the hostname, key, or action as interchangeable values: a token belongs to the integration context that created it.

Keep the CapBypass API key on your server. A browser can call your own backend, but it should not receive the CapBypass key. The examples below use the current documented endpoints, https://api.capbypass.pro/createTask and https://api.capbypass.pro/getTaskResult.

Create an Enterprise proxyless task with curl

This request uses the documented basic Enterprise proxyless schema. Replace only YOUR_API_KEY with a server-side key. The URL and site key are the documentation example values, so replace them in an authorized deployment with the values from the application you operate.

curl -sS -X POST https://api.capbypass.pro/createTask \
  -H 'Content-Type: application/json' \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "ReCaptchaV3EnterpriseTaskProxyLess",
      "websiteURL": "https://example.com",
      "websiteKey": "6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696"
    }
  }'

A successful create response contains errorId: 0 and a taskId. Persist only the task ID for the short polling operation. Do not log the API key. If the response reports an error, stop that attempt and surface the returned error description through your normal server-side error handling rather than continuing with an empty task ID.

When an action is present, add the documented optional pageAction field inside task:

"pageAction": "login"

Only add enterprisePayload when your authorized page actually uses Enterprise execute options that belong there. Do not manufacture fields from a browser trace or a generic reCAPTCHA example. The documented schema is the boundary for the API request.

Poll getTaskResult with a bounded loop

Task creation is asynchronous. Poll getTaskResult with the same key and the task ID returned by createTask. The documented ready response has status: "ready" and solution.gRecaptchaResponse.

curl -sS -X POST https://api.capbypass.pro/getTaskResult \
  -H 'Content-Type: application/json' \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "TASK_ID"
  }'

Your application should poll for a bounded period, not indefinitely. A practical implementation checks the returned JSON on every request: return the token on ready, fail immediately when an API error is reported, and otherwise wait before the next request. The CapBypass documentation example uses a two-second wait in its polling code. Keep a deadline in your own service so a stuck request cannot occupy a worker forever.

Treat the returned value as sensitive, short-lived request material. Pass it directly to the authorized form submission or server-side verification path. Avoid putting it in analytics, durable logs, URLs, or a client-visible diagnostic message.

Use Python from a server-side worker

This complete Python example uses the standard library. Set CAPBYPASS_API_KEY in the process environment rather than committing it to a source file. It creates the documented Enterprise proxyless task, polls with a two-second interval, and returns the documented response field.

import json
import os
import time
from urllib.request import Request, urlopen

API_KEY = os.environ["CAPBYPASS_API_KEY"]
BASE_URL = "https://api.capbypass.pro"


def post(path, payload):
    request = Request(
        BASE_URL + path,
        data=json.dumps(payload).encode("utf-8"),
        headers={"Content-Type": "application/json"},
        method="POST",
    )
    with urlopen(request, timeout=30) as response:
        return json.loads(response.read().decode("utf-8"))


def enterprise_token():
    created = post("/createTask", {
        "clientKey": API_KEY,
        "task": {
            "type": "ReCaptchaV3EnterpriseTaskProxyLess",
            "websiteURL": "https://example.com",
            "websiteKey": "6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696",
        },
    })
    if created.get("errorId"):
        raise RuntimeError(created.get("errorDescription", "createTask failed"))

    task_id = created["taskId"]
    deadline = time.monotonic() + 120
    while time.monotonic() < deadline:
        result = post("/getTaskResult", {"clientKey": API_KEY, "taskId": task_id})
        if result.get("errorId"):
            raise RuntimeError(result.get("errorDescription", "getTaskResult failed"))
        if result.get("status") == "ready":
            return result["solution"]["gRecaptchaResponse"]
        time.sleep(2)
    raise TimeoutError("task did not become ready before the deadline")


if __name__ == "__main__":
    print(enterprise_token())

In production, call enterprise_token() inside the backend path that owns the authorized transaction. Send the returned token to the component that performs the permitted submission, then discard it. If your page needs an action, add the documented pageAction property to the task object and keep its value aligned with the page.

Use TypeScript with the same task contract

The TypeScript version follows the same request and response contract. It uses the platform fetch API available in current Node.js runtimes. The API key is read from the process environment, and the code has a deadline and a two-second polling interval.

const apiKey = process.env.CAPBYPASS_API_KEY;
if (!apiKey) throw new Error("CAPBYPASS_API_KEY is required");

const baseUrl = "https://api.capbypass.pro";

async function post(path: string, payload: unknown): Promise<any> {
  const response = await fetch(baseUrl + path, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

async function enterpriseToken(): Promise<string> {
  const created = await post("/createTask", {
    clientKey: apiKey,
    task: {
      type: "ReCaptchaV3EnterpriseTaskProxyLess",
      websiteURL: "https://example.com",
      websiteKey: "6LdyC2cUAAAAACGuDKpXeDorzUDWXmdqeg-xy696",
    },
  });
  if (created.errorId) throw new Error(created.errorDescription || "createTask failed");

  const deadline = Date.now() + 120_000;
  while (Date.now() < deadline) {
    const result = await post("/getTaskResult", {
      clientKey: apiKey,
      taskId: created.taskId,
    });
    if (result.errorId) throw new Error(result.errorDescription || "getTaskResult failed");
    if (result.status === "ready") return result.solution.gRecaptchaResponse;
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }
  throw new Error("task did not become ready before the deadline");
}

enterpriseToken().then(console.log).catch((error) => {
  console.error(error.message);
  process.exitCode = 1;
});

The two implementations intentionally use the same task type and fields. That makes server-side observability simpler: record the task type, a request correlation ID, the task ID, the final status, and a redacted error description. Do not record API keys or response tokens.

Put the API call behind an application boundary

A clean Enterprise integration separates browser-facing code from the service that owns the CapBypass key. The browser-facing layer can request that your backend begin an authorized verification flow. The backend validates that request against its own session and authorization rules, assembles the documented task object, and performs createTask. This boundary gives the application one place to enforce which pages, actions, and environments may use the integration.

Keep the task payload small and explicit. The proxyless Enterprise task needs the page URL and website key. Add pageAction only when the page actually uses an action, and add enterprisePayload only when the documented Enterprise option is part of that page. A narrow payload is easier to review and makes it less likely that an old client field silently becomes part of a new task request.

The API key belongs in the deployment secret store or the server process environment. It should not be embedded in a JavaScript bundle, exposed in an HTML data attribute, or returned by an internal diagnostics endpoint. The code examples read CAPBYPASS_API_KEY at runtime for that reason. Give the worker that creates tasks only the configuration it needs, and redact the key from exception reporting before logs leave the service.

A request correlation ID is useful even when the task ID is the primary CapBypass identifier. Generate the correlation ID in your own application before calling createTask, associate it with the authorized user operation, and include it in structured logs. When the task is ready, record that the application received a token without recording the token itself. This lets an operator follow a request across the application, task creation, polling, and final submission without copying sensitive material into a support ticket.

Make polling predictable under load

Polling is an asynchronous coordination problem, not a background loop that should run without limits. The examples use a two-second interval because that is the wait shown in the current documentation example. Pair that interval with a deadline appropriate for your request path. If the deadline expires, return a clear timeout to the calling service and let that service decide whether an authorized user can start another attempt.

Use one poller per task ID. Starting several pollers for the same task produces duplicate requests and confusing logs without producing a different token. Store the task ID with its correlation ID until the task completes or the deadline expires. If a worker restarts, the persisted task ID lets the replacement worker decide whether the request is still inside its deadline rather than creating a second task immediately.

Distinguish three outcomes in monitoring. First, ready is a completed task with a gRecaptchaResponse that should be handed off promptly. Second, an API error is a terminal response for that task and should include only the redacted description in logs. Third, a deadline expiration is an application timeout, not proof that the API returned an error. Tracking those outcomes separately gives maintainers a useful signal without overstating what happened.

After a task becomes ready, the receiving application still owns its own verification and submission logic. The token is not a substitute for checking the action, session, and authorization rules in that application. Keep the handoff close to the permitted operation, avoid queueing a token for later reuse, and make failure messages generic to the browser while retaining redacted detail in server-side observability.

---

Bonus: +5% credits on every top-up

New to CapBypass? Apply code WELCOME_2026 at checkout for an extra 5% in credits on every top-up, with no minimum and no expiry. Redeem it on the top-up page.

---

Handle action and token lifecycle failures

An API response can be structurally valid while the receiving application rejects a token. First verify that the task type is Enterprise, not the standard v3 type. Next compare the websiteURL, websiteKey, and, when used, pageAction with the authorized page configuration. The documentation specifically notes that tokens have a short lifespan, so submit the result promptly after ready.

Separate API failures from application-side verification failures. An errorId in a CapBypass response belongs in the task workflow. A rejection after you send gRecaptchaResponse belongs in the application integration and should be examined there without exposing the token. This separation prevents a retry loop from masking a schema or context mismatch.

FAQ

Which CapBypass task type is for reCAPTCHA Enterprise v3 without my own proxy?

Use ReCaptchaV3EnterpriseTaskProxyLess. The current pricing page lists it as active, and the current reCAPTCHA v3 documentation defines it as the Enterprise v3 type that uses the service proxy.

Which fields are required for createTask?

The documented request requires clientKey, task.type, task.websiteURL, and task.websiteKey. pageAction, isSession, enterprisePayload, and apiDomain are documented optional fields. A proxy is required for the non-ProxyLess types, not for this proxyless type.

When can I use the returned token?

Use solution.gRecaptchaResponse only in the authorized integration that requested it, and use it promptly. The documentation states that reCAPTCHA v3 tokens have a short lifespan.

Should I retry forever while a task is processing?

No. Poll getTaskResult with a bounded deadline. Return on ready, stop on an API error, and fail cleanly at the deadline so the caller can decide how to recover.