Skip to content
capzy
Login

hCaptcha

Take the widget's configuration through to a response. Read the widget's public site key first. For Enterprise flows, also capture the current rqdata and match the invisible setting.

Get the integration code
POST /createTask · example
{
  "clientKey": "capzy_YOUR_API_KEY",
  "task": {
    "type": "HCaptchaTaskProxyLess",
    "websiteURL": "https://example.com/login",
    "websiteKey": "YOUR_HCAPTCHA_SITE_KEY"
  }
}

Illustrative values. Replace the inputs with values from your current integration.

Page URL + hCaptcha site keyProxyless or your own proxyhCaptcha response token

Locate the hCaptcha site key.

Read the widget's public site key first. For Enterprise flows, also capture the current rqdata and match the invisible setting.

Your API key authenticates Capzy.
Provider keys, challenge IDs, images, and session values belong inside task.

Locate the hCaptcha site key.

  1. In Elements, find the h-captcha container and copy data-sitekey. For a dynamic widget, search Sources for hcaptcha.render and read sitekey in its options.
  2. Copy the full widget page URL into websiteURL. Inspect data-size or size in the render options to identify invisible mode.
  3. If you manage the widget, compare the public key with its Sites configuration in your hCaptcha account.
Input collection example - replace illustrative values
<div class="h-captcha"
  data-sitekey="YOUR_HCAPTCHA_SITE_KEY"
  data-size="normal">
</div>

invisible is Capzy's task setting. Match the actual widget's mode rather than whether its checkbox is currently on screen.

Provider integration documentation
How hCaptcha works

hCaptcha is a privacy-focused captcha service. It presents a checkbox and may show image classification challenges ('Select all images containing a bicycle'). hCaptcha Enterprise adds additional behavioral analysis and device fingerprinting for higher security sites.

Capzy's proprietary solver returns valid hCaptcha tokens for authorized testing and automation. Standard and Enterprise variants are both supported.

  • Checkbox + image challenge solving
  • Enterprise variant support
  • Capzy proprietary classification — no human workers
  • Works on every standard and Enterprise hCaptcha deployment
  • Proxy support for IP-sensitive sites
  • High accuracy image classification

Know what goes in.

Choose a field to see its purpose, where to get it, and its place in the request. Optional values omitted from the example can be added when your flow uses them.

Use the standard hCaptcha task for a standard site key. Match invisible mode to the widget.

Request authentication

Required task inputs

Optional context

websiteURL

stringRequired

The page URL where hCaptcha is loaded — the token is bound to this origin

Where it comes from

Copy the full page URL from the address bar or the document request in Network, including the path where this flow runs.

Open the input guide
Example valuehttps://example.com/login
POST /createTask · selected configuration
{
  "clientKey": "capzy_YOUR_API_KEY",
  "task": {
    "type": "HCaptchaTaskProxyLess",
    "websiteURL": "https://example.com/login",
    "websiteKey": "YOUR_HCAPTCHA_SITE_KEY"
  }
}

The selected field is highlighted when present. Preserve the declared value type and current challenge context.

Make your first request.

Create the task, keep its taskId, and poll until status is ready. Then read the selected variant's solution.

More examples
  1. Create the task

    Send clientKey and the selected task to /createTask from your server. Keep the returned taskId.

  2. Wait for the solution

    Send that same key and ID to /getTaskResult. While processing, wait two seconds before checking again. Stop on Ready or an error.

  3. Apply the result

    Put solution.token into the existing h-captcha-response field or pass it to the configured callback. Keep your Capzy API key on the server; only the returned response token is needed by the browser form.

HCaptchaTaskProxyLess · Price unavailable / 1,000
solve_hcaptcha.py
import json, os, time
import requests

API = "https://api.capzy.ai"
KEY = os.environ["CAPZY_API_KEY"]
task = json.loads("{\"type\":\"HCaptchaTaskProxyLess\",\"websiteURL\":\"https://example.com/login\",\"websiteKey\":\"YOUR_HCAPTCHA_SITE_KEY\"}")

def call(path, payload):
    response = requests.post(f"{API}/{path}", json={"clientKey": KEY, **payload}, timeout=30)
    response.raise_for_status()
    data = response.json()
    if data.get("errorId", 0) or data.get("status") == "failed":
        raise RuntimeError(data.get("errorDescription") or data.get("errorCode") or "Task failed")
    return data

created = call("createTask", {"task": task})
for attempt in range(60):
    result = call("getTaskResult", {"taskId": created["taskId"]})
    if result.get("status") == "ready":
        solution = result["solution"]
        print(solution)
        break
    time.sleep(2)
else:
    raise TimeoutError("Task is still processing; keep the taskId to check it later.")

Before runningReplace all illustrative inputs with your captured values. Set CAPZY_API_KEY in your environment. Install requests with pip install requests.

Polling and failuresThe example checks HTTP/API failures, uses 30-second request timeouts, and stops after 60 result checks. Retain taskId if your task is still processing.

Understand what comes back.

Follow this task from creation to completion. Response fields and usage follow your selected request variant.

hCaptcha response token

Put solution.token into the existing h-captcha-response field or pass it to the configured callback. Keep your Capzy API key on the server; only the returned response token is needed by the browser form.

string
The solved hCaptcha token. Submit in h-captcha-response field
POST /getTaskResult · example response
{
  "errorId": 0,
  "status": "ready",
  "solution": {
    "token": "P0_eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...<long hCaptcha JWT>..."
  }
}

Illustrative values. Additional metadata may be returned; only Ready contains a completed solution.

Submit h-captcha-response

Submit solution.token with the original form as h-captcha-response. Your backend verifies the response; keep provider secrets on the server.

Execution context result is the parsed Ready response from the polling example. session, when referenced, is your existing requests.Session (or browser-compatible session) with the original cookie jar, headers, and solving proxy configured in session.proxies for both http and https. Keep this client for the complete flow. task is the task object you submitted. For Shape, action_body is the original protected request body as bytes or a string, with its original Content-Type in session.headers. Install curl_cffi when the fragment imports it; match the target's required browser/TLS identity.

Use the result · Python
token = result["solution"]["token"]
# Keep the original form's action, other fields, and session.
response = session.post("https://target.example.com/submit", data={
    "h-captcha-response": token,
    # Add the original application form fields here.
}, timeout=30)

When something doesn't work.

Check your captured values, the selected variant, and the response before starting another task.

Do you solve the image challenges?

Yes. When hCaptcha shows image grid challenges, our proprietary classifier identifies the correct images automatically.

What about hCaptcha Enterprise?

Use the Enterprise task type (HCaptchaEnterpriseTaskProxyLess / HCaptchaEnterpriseTask) and, if the site presents rqdata, forward that string in the rqdata param. The solve path is otherwise identical to standard — there is no isEnterprise flag; rqdata is the only Enterprise-specific input.

When do I need rqdata?

Only if the site is Enterprise and its captcha config returns an rqdata value (you'll see it in the getcaptcha/checksiteconfig response or the widget's data-rqdata). Pass it verbatim; the token is cryptographically bound to it, so a token minted without it will fail siteverify.

What does oneClick do?

It's a fast, cheap best-effort mode: we load the widget, do a single click, and return the token if hCaptcha passively passes — instead of waiting out an image challenge. Use it when you want a quick attempt on clean IPs.

How do I inject the token?

Set the value of textarea[name='h-captcha-response'] and input[name='h-captcha-response'] to the token, then submit the form.

Connect hCaptcha to your workflow.

Get your Capzy API key and use this guide's integration.

Get an API key Full API documentation
UnavailablePer 1,000 solves
UnavailableAverage solve time

HCaptchaTaskProxyLess · Live configuration
Current stats are unavailable. Check the solver catalog.