DataDome Solver API

The returned datadome cookie is bound to the network and browser context that produced it. Reuse the same egress IP and the returned useragent when you submit it, otherwise the cookie usually fails even though the task completed; see proxy, User-Agent and cookie consistency for the checks to run first.

Requires the page that triggers the challenge, websiteURL, the full DataDome challenge address captchaUrl, and an HTTP proxy. captchaUrl is the challenge page URL, not the ordinary target page URL; this type does not accept a custom useragent field.

Build the challenge URL (free)

Call POST /v1/datadome/build-url with a valid SolveHub API Key having tasks scope and an active account. This synchronous helper creates no task and reserves or charges no balance. Provide websiteURL and at least one of body (captured HTML or JSON, up to 1 MiB), location or captchaUrl (up to 4096 bytes each). A supplied captchaUrl takes precedence. Send captured content for parsing; do not execute its JavaScript in your client.

curl -sS -X POST 'https://www.tiam.codes/v1/datadome/build-url' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  --data '{"websiteURL":"https://example.com/login","body":"{\"url\":\"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE\"}"}'

{"captchaUrl":"https://geo.captcha-delivery.com/captcha/?cid=EXAMPLE","challengeType":"captcha"}

The response contains captchaUrl and challengeType (captcha or interstitial). Pass the URL unchanged to the DataDome task below. Only the solving task reserves and settles its current price. Captures should be fresh and belong to the same session and proxy IP. The compatibility route POST /buildDataDomeUrl accepts a SolveHub Key in JSON clientKey and returns the errorId format.

Browser selection

Optional useragent selects browser family, platform and major version for Chrome/Chromium or Firefox. An unavailable version causes a task failure. Omit it to use the default browser. Replay cookies with the same proxy and the actual solution.useragent, rather than assuming the requested string is the returned identity.

Without useragent, DataDome uses its default macOS desktop Chrome profile; the browser version follows the node inventory.

Request fields

The outer type and task are required; all task.* paths below are inside the task object. Field names are case-sensitive. Length limits are measured in UTF-8 bytes.

Create request example

{
  "type": "datadome",
  "task": {
    "websiteURL": "https://example.com/product",
    "captchaUrl": "https://example.com/captcha/?example=1",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}

cURL call

Replace the Key, site information, and proxy in the example with your actual values; keep the Idempotency-Key unchanged for the same business request.

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-datadome-0001' \
  --data-binary @- <<'JSON'
{
  "type": "datadome",
  "task": {
    "websiteURL": "https://example.com/product",
    "captchaUrl": "https://example.com/captcha/?example=1",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080"
  }
}
JSON

Create response and polling

A successful creation returns HTTP 202, and the initial status is usually queued. Save the taskId and call GET /v1/tasks/{taskId} roughly every 2–3 seconds. The soft processing time limit for this type is 240 seconds; after the soft limit the task may enter uncertain. Results of accepted tasks can still be verified; clients should not blindly recreate the task with a new Idempotency-Key.

Result fields

Read solution only when status=completed; the table below lists common fields, and the actual fields are those in the task's response.

After completion, get the cookie from solution.cookies.datadome, and access the target using solution.useragent and the same proxy. Sample result: {"cookies":{"datadome":"EXAMPLE_COOKIE"},"useragent":"Mozilla/5.0 ..."}. The target site's real captchaUrl must be obtained from the actual challenge flow.

Failures and troubleshooting

captchaUrl should be the full URL of the current challenge; do not strip the session query parameters. If the cookie is invalid, check that the same proxy egress and User-Agent are used.

Common errors on create requests are 400 INVALID_TASK, 402 INSUFFICIENT_BALANCE, 429 TASK_LIMIT_EXCEEDED, and 503 TYPE_UNAVAILABLE. When a created task fails, the public error code is TASK_FAILED or TASK_TIMEOUT; uncertain corresponds to TASK_UNCERTAIN. See the Platform API reference for details.

The processing window starts after task creation is confirmed; queue waiting does not consume it. The current node timeout is approximately 210 seconds; the platform allows a 240-second soft window for transport and result polling.

Supported User Agents