CAPTCHA solving API reference

POST /createTask Create a task

Body: clientKey and a task object. The task type decides the other fields; see Task types. Answer: errorId 0 and taskId, or errorId 1 with errorCode.

POST https://unlock-api.com/createTask
{"clientKey":"YOUR_API_KEY","task":{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"0x4AAAAAAAC3DHQFLr1GavRN"}}

{"errorId":0,"taskId":1001}
{"errorId":1,"errorCode":"ERROR_ZERO_BALANCE","errorDescription":"..."}

POST /getTaskResult Get the result

Body: clientKey and taskId. While the task runs: status processing. When it is done: status ready with the solution and the cost. A failed task answers errorId 1 with its errorCode.

POST https://unlock-api.com/getTaskResult
{"clientKey":"YOUR_API_KEY","taskId":1001}

{"errorId":0,"status":"processing"}
{"errorId":0,"status":"ready","solution":{"token":"0.zrSnRHO7h0..."},"cost":"0.0012","createTime":1791640000,"endTime":1791640011,"solveCount":1}

POST /getBalance Get the balance

Body: clientKey. Answer: balance in US dollars.

{"clientKey":"YOUR_API_KEY"}

{"errorId":0,"balance":42.5}

Report a wrong answer

reportIncorrectRecaptcha and reportIncorrectImageCaptcha accept clientKey and taskId and answer success. They are accepted for compatibility with existing libraries; a report does not change the charge.

Send a task: in.php

Fields: key, method and the fields of the CAPTCHA type. Answer: OK|ID, or with json=1 {"status":1,"request":"ID"}. Errors come back as their names, such as ERROR_ZERO_BALANCE.

POST https://unlock-api.com/in.php
key=YOUR_API_KEY&method=hcaptcha&sitekey=SITE_KEY&pageurl=https://example.com&json=1

OK|1001
{"status":1,"request":"1001"}

Get the answer: res.php

action=get&id=ID returns OK|ANSWER when solved and CAPCHA_NOT_READY while working. action=get2 adds the cost. ids=ID1,ID2 checks up to 100 tasks at once. action=getbalance returns the balance. action=reportbad and reportgood are accepted.

GET https://unlock-api.com/res.php?key=YOUR_API_KEY&action=get&id=1001
CAPCHA_NOT_READY
OK|P1_eyJ0eXAiOiJKV1Qi...

GET https://unlock-api.com/res.php?key=YOUR_API_KEY&action=getbalance
42.5

POST /getToken Create and wait: getToken

Same body as createTask. The call waits up to 50 seconds and returns the same reply as getTaskResult. If the task is still running, the reply is status processing with its taskId; keep polling getTaskResult.

POST https://unlock-api.com/getToken
{"clientKey":"YOUR_API_KEY","task":{"type":"TurnstileTaskProxyless","websiteURL":"https://example.com","websiteKey":"0x4AAAA..."}}

{"errorId":0,"taskId":1001,"status":"ready","solution":{"token":"0.zrSnRHO7h0..."},"cost":"0.000725"}

Result callbacks

Add callbackUrl to createTask (or pingback to in.php) and the result is sent there when the task finishes: a JSON body like getTaskResult with taskId, or for in.php a form body id=…&code=…. Only public addresses are called, once, with a 5 second timeout; the result also stays available through polling.

{"clientKey":"YOUR_API_KEY","callbackUrl":"https://your.server/captcha-result","task":{...}}

POST https://your.server/captcha-result
{"errorId":0,"taskId":1001,"status":"ready","solution":{...},"cost":"0.0005"}

Statistics

getQueueStats returns tasks waiting and being solved now and the average solve time in the last hour. getSpendingStats returns your volume and money per hour for one UTC day (date as unix time). test echoes the body it receives.

POST https://unlock-api.com/getQueueStats     {"clientKey":"..."}  ->  {"errorId":0,"waiting":3,"solving":12,"speed":6.4,"total":15}
POST https://unlock-api.com/getSpendingStats  {"clientKey":"...","date":1791590400}  ->  {"errorId":0,"data":[{"dateFrom":...,"volume":120,"money":0.06},...]}
POST https://unlock-api.com/test              {"anything":1}  ->  {"errorId":0,"received":{"anything":1}}

IP allow list

If you set an IP allow list on the account page, requests from other IPs get ERROR_IP_NOT_ALLOWED.