Solverify CAPTCHA API Documentation

Solverify is an asynchronous CAPTCHA-solving and bot-challenge API for developers. Create a task, poll for its result, and receive structured solution data such as a response token, browser cookies, headers, user-agent, HTML, or OCR text.

This documentation explains how to integrate Solverify with Cloudflare Turnstile, Cloudflare Interstitial, PerimeterX, DataDome, Akamai Bot Manager, Aliyun Captcha 2.0, Imperva, AWS WAF, Alibaba x5sec NoCaptcha, and image-to-text OCR workflows.

Use Solverify only on websites, accounts, and automation workflows where you have permission to perform automated checks.

Quick Start

Every Solverify task follows the same basic lifecycle:

1. Obtain your API key and keep it in a server-side environment variable.
2. Send a task-specific payload to POST /createTask.
3. Save the taskId returned by the API.
4. Poll POST /getTaskResult every 2 to 3 seconds.
5. Stop polling when the status is completed or the API returns an error.
6. Read the task-specific fields from solution.

The base URL for all customer API requests is:

https://solver.solverify.net

All request and response bodies use JSON unless an endpoint page states otherwise.

Authentication

Customer endpoints authenticate with the clientKey field in the JSON request body:

{
  "clientKey": "YOUR_API_KEY"
}

Treat your API key as a secret. Store it in a server-side secret manager or environment variable, do not commit it to source control, and never expose it in browser JavaScript or a public mobile application.

Create Your First CAPTCHA Task

The following example creates a proxyless Cloudflare Turnstile task. Other challenge types use the same endpoint but require different fields inside task.

curl --request POST \
  --url https://solver.solverify.net/createTask \
  --header "Content-Type: application/json" \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "turnstile",
      "websiteURL": "https://example.com/",
      "websiteKey": "0x4AAAAAAA..."
    }
  }'

A successfully accepted task returns a unique identifier:

{
  "errorId": 0,
  "taskId": "TASK_UUID"
}

Task creation is asynchronous. Receiving a taskId means the request was accepted, not that solving has finished.

Poll for the Task Result

Send the returned task ID to the Get Task Result API:

curl --request POST \
  --url https://solver.solverify.net/getTaskResult \
  --header "Content-Type: application/json" \
  --data '{
    "clientKey": "YOUR_API_KEY",
    "taskId": "TASK_UUID"
  }'

The endpoint returns immediately with the task's current status:

Do not send rapid, continuous requests while a task is pending or processing. Use a bounded polling loop with a 2-to-3-second delay and an overall deadline appropriate for the selected task type.

Understand the Solution

Completed tasks return a task-specific solution. Depending on the selected solver, it may contain:

Always follow the task-specific page when interpreting a solution. A Turnstile token is consumed differently from a DataDome cookie or an Aliyun verification payload.

Supported CAPTCHA and Bot Challenge APIs

Choose the task type that matches the challenge displayed by the target application.

Token-Based Tasks

Token-based solvers return a value that the authorized application can submit to its normal verification flow. Cloudflare Turnstile is the primary token-based integration. Provide the exact page URL and site key from the target widget.

Cookie-Based Browser Tasks

Interstitial and anti-bot integrations generally return browser cookies. For these tasks, session consistency is critical:

• Replay all returned cookies, not only the best-known cookie name.
• Reuse the user-agent returned in solution.useragent.
• Keep the same proxy IP when the challenge result is IP-bound.
• Use a sticky proxy session when multiple requests must share one identity.
• Consume short-lived cookies promptly.

OCR Tasks

OCR tasks accept a Base64-encoded image and return extracted text. They do not use a website URL or proxy. The solver accepts both raw Base64 and image data URIs such as data:image/png;base64,...; see the OCR guide for encoding and size limits.

Proxy Configuration

Proxy-based tasks support HTTP proxies with these fields:

{
  "proxyType": "http",
  "proxyAddress": "1.1.1.1",
  "proxyPort": "8080",
  "proxyLogin": "username",
  "proxyPassword": "password"
}

Only http is accepted as proxyType. proxyPort is sent as a numeric string. proxyLogin and proxyPassword are needed only for proxies that require authentication.

Some task types require a proxy during validation. Others permit proxyless solving but return cookies or tokens bound to the solver infrastructure IP, making those results unsuitable for replay from your own backend. Review the individual solver guide before creating the task.

API Reference

Errors and HTTP Responses

Solverify responses include a numeric errorId:

• errorId: 0 means the operation succeeded or the task remains active.
• errorId: 1 means the request or task failed; inspect errorCode and errorDescription.

Customer-facing validation and application errors are usually represented in a JSON response with HTTP 200. Your integration must inspect the response body instead of treating every HTTP 200 response as a successful solve.

Common error categories include:

• Invalid JSON, missing fields, or unsupported task parameters.
• Invalid API keys or inaccessible task IDs.
• Insufficient account balance.
• Account concurrency limits.
• Temporary solver capacity shortages.
• Challenge failures and task timeouts.

See Solverify API Error Codes for exact codes, descriptions, and retry guidance.

Balance and Concurrency

Check your balance with POST /getBalance before creating work when your application needs to prevent insufficient-funds failures. You can also inspect account details through the Profile API.

Pay-per-solve accounts have a default limit of 20 active tasks unless a different limit has been configured. Use POST /activeTasks to inspect current work and implement a queue in your application rather than submitting beyond the available concurrency.

Integration Best Practices

• Keep clientKey on trusted server infrastructure.
• Validate URLs, site keys, scripts, images, and proxy credentials before submission.
• Use the exact case shown for task-specific fields such as WafScriptUrl and ApiURL.
• Poll every 2 to 3 seconds instead of using a tight loop.
• Set both per-request timeouts and an overall task deadline.
• Stop polling immediately after completion or failure.
• Log taskId, status, errorCode, and elapsed time without logging API keys or proxy passwords.
• Retry transient capacity or transport failures with bounded backoff and jitter.
• Do not automatically retry invalid requests or insufficient-balance responses.
• Replay cookie-based results with the returned user-agent and the same proxy session when required.

Platform Limits

• The maximum HTTP request body size is 10 MB.
• OCR image data has a stricter task-specific limit documented in the OCR API guide.
• Target URLs and task fields have validation limits that vary by task type.
• Only HTTP proxies are supported by customer proxy fields.
• Task timeouts vary by solver and are listed on each task page.

Frequently Asked Questions

What is the Solverify API?

Solverify is an asynchronous API for solving supported CAPTCHA, browser interstitial, anti-bot, and OCR challenges. It returns structured data that a developer can consume in an authorized integration.

Which endpoint creates a CAPTCHA-solving task?

Send POST https://solver.solverify.net/createTask with your clientKey and a supported task object. The response contains the taskId used for result polling.

How often should I request a task result?

Poll POST /getTaskResult every 2 to 3 seconds. Continue only while the task is pending or processing.

Does every task require a proxy?

No. OCR does not use a proxy, and Turnstile supports proxyless tasks. Imperva, AWS WAF, and Alibaba x5sec also permit proxyless submission, although a replayable proxy may be necessary for useful cookie-based results. Other browser task types require an HTTP proxy.

Why should I reuse the solver user-agent?

Cookie-based anti-bot systems can bind results to a browser fingerprint. Reusing solution.useragent, all returned cookies, and the same proxy IP helps preserve the solved session context.

Why did I receive HTTP 200 with an error?

Solverify commonly returns customer-facing errors as JSON with errorId: 1. Always inspect errorId, errorCode, and errorDescription, even when the HTTP request itself succeeded.

Where can I see pricing or account balance?

Use the Get Balance API for the current account balance and the Profile API for account information.

Where can I get integration support?

For custom throughput, integration assistance, or account support, contact Solverify through Telegram.