UNLOCK API
Get an API key
Result callbacks
MarkdownOpenAPI

Result callbacks

Get the result sent to your server instead of checking for it.

JSON methods

Add callbackUrl to createTask. When the task is done, the result is sent to that address by POST with a JSON body shaped like getTaskResult, plus taskId. A failed task sends errorId 1 with errorCode.
POST /createTask
{
  "clientKey": "YOUR_API_KEY",
  "callbackUrl": "https://your-server.com/captcha-result",
  "task": {
    "type": "TurnstileTaskProxyless",
    "websiteURL": "https://example.com/login",
    "websiteKey": "0x4AAAAAAAC3DHQFLr1GavRN"
  }
}
POST https://your-server.com/captcha-result
{
  "errorId": 0,
  "taskId": 1001,
  "status": "ready",
  "solution": {
    "token": "0.zrSnRHO7h0HwSjSCU8oyzbjEtD8p..."
  },
  "cost": "0.00055",
  "createTime": 1791640000,
  "endTime": 1791640011,
  "solveCount": 1
}

Form API

Add pingback to in.php. When the task is done, the address gets a POST form body with id (the task id) and code (the answer, or the error name).
in.php
curl -s "https://unlock-api.com/in.php" -d "key=YOUR_API_KEY&method=turnstile&sitekey=SITE_KEY&pageurl=https://example.com/login&pingback=https://your-server.com/captcha-result"

# POST https://your-server.com/captcha-result
# Content-Type: application/x-www-form-urlencoded
# id=1001&code=0.zrSnRHO7h0HwSjSCU8oyzbjEtD8p...

Rules

  • The address must be public http or https. Private, local and loopback addresses are not called.
  • One attempt with a 5 second timeout. The result also stays available with getTaskResult and res.php, so keep a fallback check.
  • The reply from your server is not checked, and a failed delivery is not retried.