Skip to content

PopularCaptcha

PopularCaptcha is our unified token endpoint for hCaptcha and other hCaptcha-style challenges. It returns a verified token you can submit back to the target site without managing the underlying image puzzles yourself.

How to Use

Create the task with the `createTask` method and poll for the result using the `getTaskResult` method.

Task Type Aliases

Both `PopularCaptchaTask` and `PopularTask` are accepted as the `task.type` value (case-insensitive — `populartask` works too).

1. Create Task

Use the `createTask` method to initiate the solving process. You must provide the `websiteURL` and `websiteKEY`, plus a `proxy` and optional `metadata` for Enterprise-style challenges.

Task Object Parameters

PropertyTypeRequiredDescription
typeStringYesMust be `PopularCaptchaTask` or `PopularTask` (alias).
websiteURLStringYesThe full URL of the target page where the challenge appears.
websiteKEYStringYesThe PopularCaptcha / hCaptcha `site-key` found on the target page.
proxyStringYesProxy connection string, e.g. `http:user:pass@host:port`.
metadataObjectNoOptional extra fields for Enterprise-style challenges.
metadata.rqdataStringNoEnterprise `rqdata` JWT, when present on the target.
metadata.rqtokenStringNoEnterprise `rqtoken` value, when issued by the target.
metadata.fingerprintStringNoOptional client fingerprint to forward with the solve.

Example Request

POST https://api.captchasonic.com/createTask
Host: api.captchasonic.com
Content-Type: application/json
{
    "apiKey": "",
    "task": {
        "type": "PopularCaptchaTask",
        "websiteURL": "https://example.com/login",
        "websiteKEY": "8e58fe8c-1a48-4f94-88ae-8e90b586a192",
        "proxy": "http:user:pass@host:port",
        "metadata": {
            "rqdata": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
            "rqtoken": "...",
            "fingerprint": "..."
        }
    }
}

Example Response

A successful creation request returns a taskId which you will use in the next step.

{
    "errorId": 0,
    "status": "idle",
    "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

2. Get Result

After creating a task, use the `getTaskResult` method to check the status and retrieve the solution. Poll this endpoint every 3-5 seconds until the status is `completed`.

Example Request

POST https://api.captchasonic.com/getTaskResult
Host: api.captchasonic.com
Content-Type: application/json
{
    "apiKey": "YOUR_API_KEY",
    "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

Example Success Response

When the task status becomes completed, the response will contain the solution object.

{
    "errorId": 0,
    "status": "completed",
    "solution": {
        "token": "P1_eyJ0eXAiOi...solution..token..here...J9",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
    },
    "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}

SDK Usage

# pip install --upgrade captchasonic
#
# from captchasonic import CaptchaSonic
#
# client = CaptchaSonic(api_key="YOUR_API_KEY")
#
# solution = client.solve_hcaptcha_token(
#   website_url="https://example.com/login",
#   website_key="8e58fe8c-1a48-4f94-88ae-8e90b586a192"
# )
# print(solution.token)

Full Sample Code

import requests
import time

API_KEY = "YOUR_API_KEY"
API_URL = "https://api.captchasonic.com"

def solve_popular_captcha():
    print("Creating PopularCaptcha task...")
    create_payload = {
        "apiKey": API_KEY,
        "task": {
            "type": "populartask",
            "websiteURL": "https://example.com/login",
            "websiteKey": "8e58fe8c-1a48-4f94-88ae-8e90b586a192"
        }
    }
    res = requests.post(f"{API_URL}/createTask", json=create_payload)
    if res.status_code != 200:
        print(f"Error creating task: {res.text}")
        return

    task_id = res.json().get("taskId")
    if not task_id:
        print(f"Could not find taskId in response: {res.json()}")
        return

    print(f"Task created. Task ID: {task_id}")

    while True:
        print("Polling for result...")
        time.sleep(3)
        get_payload = {"apiKey": API_KEY, "taskId": task_id}
        res = requests.post(f"{API_URL}/getTaskResult", json=get_payload)
        if res.status_code != 200:
            print(f"Error getting result: {res.text}")
            continue

        resp_json = res.json()
        status = resp_json.get("status")
        if status == "completed":
            print("Task completed!")
            return resp_json.get("solution")
        elif status == "failed":
            print(f"Task failed: {resp_json.get('errorDescription')}")
            return
        elif status == "processing":
            print("Task is still processing, trying again...")
        else:
            print(f"Unknown status: {status}, response: {resp_json}")

solution = solve_popular_captcha()
if solution:
    print("\n--- SOLUTION ---")
    print(f"Token: {solution.get('token')[:30]}...")
    print("----------------")