API documentation to Bypass captchas

To use our service for solving captcha and recaptcha, one has to use the API.

In order to use the API, you need to have an account with bestcaptchasolver.com, some credit into it and the access token string. The access token can be gathered from the /account page.

The authentication against the API endpoints is made using the access token.

To make things easier, we've developed API libraries so that you don't have to worry about implementing our API. For those that want to implement their own API libraries, or they can't find a library for the particular programming language, this document is meant to help you achieve that.

Requests and responds are in JSON.

Libraries

Automation

We've created few automation examples for you, with browser and with pure requests to get a better idea on how to integrate our service with automation software which can be found on our /bypass-captcha-solver-automation page

Balance

GET https://bcsapi.xyz/api/user/balance?access_token={YOUR_ACCESS_TOKEN}

Query parameters:

  • access_token

Returns the balance of the user. Balance is shown in USD.

Returns

{
    "status": "success",
    "balance": "5.2164"
}

Image captcha

The process of completing a captcha image, consists of two parts:

  • submission - submit the captcha image as B64 encoded string, which returns an ID
  • retrieval - use the ID received in the submission, to check for captcha completion

Submit

POST https://bcsapi.xyz/api/captcha/image

Body paramaters:

{
    "b64image":"/9j/4AAQSkZJRgAB...iiigD//2Q==",
    "access_token":"your_access_token"
}
  • b64image - image encoded as a B64 string
  • access_token - user's access_token
  • is_case (optional) - set to true or 1 if captcha is case sensitive
  • is_phrase (optional) - if captcha text is a phrase (contains at least one space), set to true
  • is_math (optional) - instructs worker that a math captcha has to be calculated, set to true
  • alphanumeric (optional) - set to 1 if captcha text contains digits only, set it to 2 letters only
  • minlength (optional) - minimum length of captcha text, i.e 5, default: any
  • maxlength (optional) - maximum length of captcha text, i.e 8, default: any
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 25,
    "status": "submitted"
}

The ID in this case would be 25. Use that in order to retrieve the actual text of the image.

The limit of post data is 10mb. In other words, image size cannot exceed 10mb

[Update]

The request made to this submission endpoint responds differently compared to other captcha types. It returns the ID (response to submission request) after the captcha was solved by a worker, in other words, it takes more for the submission request to go through and to get the ID of the captcha.

Once you received the ID though, you can make the request for retrieval of the text solution right after, without any delay.

Retrieve

GET https://bcsapi.xyz/api/captcha/{CAPTCHA_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • captcha_ID - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
     "id": 25,
     "text": "polum",
     "status": "completed"
}

As soon as you received an ID for your image captcha, use this endpoint to retrieve the text, it's already completed at this point

reCAPTCHA

  • UPDATE 15.01.2021 - Added reCAPTCHA Enterprise support (v2 & v3)
  • UPDATE 27.07.2018 - Added reCaptcha V3 support

In order to bypass recaptcha, there are (at least) two things that you need to know:

  • page url - URL on which you encounted the captcha
  • site key - recaptcha (public) sitekey, which can be found in the website's source

Same as with image captcha, the process of solving the reCAPTCHA consists of two parts:

  • submit captcha details
  • receive g-response (the g-response will be used to bypass the captcha on the page)

The bypassing of recaptcha takes more time then solving regular image captcha.

Once you've submitted the captcha details (page url and sitekey) the completion time will be ~30 seconds.

Submit

POST https://bcsapi.xyz/api/captcha/recaptcha

Body paramaters:

{
    "page_url":"http://website.com",
    "site_key":"6fd45trQJsd...br",
    "access_token": "your_access_token"
}
  • access_token - user's access token
  • page_url - recaptcha page URL
  • site_key - sitekey (public key) of recaptcha
  • type (optional) - defaults to value 1 (that is, v2) if not given
    • 1 - v2
    • 2 - invisible
    • 3 - v3
    • 4 - enterprise v2
    • 5 - enterprise v3
  • v3_action (optional) - action value used when solving v3 recaptcha, leave empty if no action
  • v3_min_score (optional) - minimum score targeting when solving v3, float, i.e 0.4
  • domain (optional) - domain used to load reCAPTCHA interface, defaults to www.google.com, an alternative would be recaptcha.net
  • data_s (optional) - recaptcha data-s value used in loading reCAPTCHA
  • cookie_input (optional) - used in loading reCAPTCHA
  • user_agent (optional) - user-agent used to load captcha interface
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 26,
    "status": "submitted"
}

Retrieve

Same as captcha image retrieval, request is done in the same way. Only thing that differs is the response. What's different is that instead of the text parameter in return you get the gresponse parameter.

GET https://bcsapi.xyz/api/captcha/{RECAPTCHA_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • recaptcha_ID - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
     "id": 25,
     "gresponse": "03AJpayVFactgTmHlV...",
     // v3 score (of our test captcha) if submission type is v3
     "v3_score": "0.3",
     // returned in some cases, if you want to make sure cookie_output is also returned
     // submit captcha with cookie_input
     "cookie_output": "NID:22=AvGseFW...SDwfg4",    
     "status": "completed",
     "proxy_status": "status of proxy (if used)",
     "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36"
}

The gresponse is used to bypass the captcha on the website. It's very different, depending on the website. Usually, in case of a browser automation, you set the gresponse received from our service, in the page's DOM, using JavaScript.

If it's automation based on pure requests, normally the gresponse is submitted with the request itself, whether that's a login, registration, etc.

GeeTest

Required parameters for solving through bestcaptchasolver service:

  • domain
  • gt
  • challenge (unique)
  • api_server (optional)

IMPORTANT !

Geetest challenge works only once ! If you submit a captcha with a challenge, you can't reuse the same challenge anymore, captcha won't get solved

Submit

POST https://bcsapi.xyz/api/captcha/geetest

Body paramaters:

{
    "domain":"http://website.com",
    "gt":"8a7610...fd7f58bb",
    "challenge":"dd44ab5...c056f7d5",
    // "api_server": "api.geetest.com",
    "access_token": "your_access_token"
}
  • access_token - user's access token
  • domain - page / domain on which you encountered the captcha
  • gt - gt (geetest) parameter
  • challenge - unique GeeTest challenge, required for solving captcha (gets invalidated after 1st use)
  • api_server - geetest domain - optional
  • user_agent (optional) - user-agent used to load captcha interface
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 30,
    "status": "submitted"
}

Retrieve

GET https://bcsapi.xyz/api/captcha/{GEETEST_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • geetest_id - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
    "id":30,
    "solution": {
        "challenge":"8ab8af73c1...ffc63f5f",
        "validate":"d628bb2...fb097e6546",
        "seccode":"d628bb213...dfb097e6546|jordan"
    },
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
    "status":"completed"
}

Use the data inside the solution object in order to bypass the GeeTest captcha page.

GeeTestV4

Required parameters for solving through bestcaptchasolver service:

  • domain
  • captchaid

Submit

POST https://bcsapi.xyz/api/captcha/geetestv4

Body paramaters:

{
    "domain":"http://website.com",
    "captchaid":"647f5ed2ed8acb4be36784e01556bb71"
}
  • access_token - user's access token
  • domain - page / domain on which you encountered the captcha
  • captchaid - this is not the captchaid that's in our system that you receive while submitting a captcha. Gather this from HTML source of page with captcha, inside the <script> tag you'll find a link that looks like this: https://i.imgur.com/XcZd47y.png
  • user_agent (optional) - user-agent used to load captcha interface
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 30,
    "status": "submitted"
}

Retrieve

GET https://bcsapi.xyz/api/captcha/{GEETEST_V4_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • geetest_v4_id - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
    "id":30,
    "solution": {
        "captcha_output" : "fI9I34MDj...smKREaJBuOqzIGp28oxCv5eI84w-LUBLvGJfRc",
        "gen_time" : "1649952023",
        "pass_token" : "1bd276f00d743d...b644ac6c0980dce44ff8f577",
        "lot_number" : "f8d3b81a591745d5b8c065d2d7c604b5",
        "captcha_id" : "647f5ed2ed8acb4be36784e01556bb71",
    },
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
    "status":"completed"
}

Use the data inside the solution object in order to bypass the GeeTestV4 captcha page.

Capy

Required parameters for solving through bestcaptchasolver service:

  • page_url
  • site_key

Submit

POST https://bcsapi.xyz/api/captcha/capy

Body paramaters:

{
    "page_url":"http://website.com",
    "site_key":"Cme4hZL...2D3uNms5w",
    "access_token": "your_access_token"
}
  • access_token - user's access token
  • page_url - page / domain on which you encountered the captcha
  • site_key - sitekey for captcha, can be gathered from source / DOM of page
  • user_agent (optional) - user-agent used to load captcha interface
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 30,
    "status": "submitted"
}

Retrieve

GET https://bcsapi.xyz/api/captcha/{CAPY_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • capy_id - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
    "id":30,
    "solution": "0x0x8ex0xax84x0...x1ix0x76x18x",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
    "status":"completed"
}

hCaptcha

Required parameters for solving through bestcaptchasolver service:

  • page_url
  • site_key

Submit

POST https://bcsapi.xyz/api/captcha/hcaptcha

Body paramaters:

{
    "page_url":"http://website.com",
    "site_key":"Cme4hZL...2D3uNms5w",
    "access_token": "your_access_token"
}
  • access_token - user's access token
  • page_url - page / domain on which you encountered the captcha
  • site_key - sitekey for captcha, can be gathered from source / DOM of page
  • invisible (optional) - set it when hcaptcha is invisible
  • payload (optional) - extra parameters, useful for enterprise version, JSON object
  • domain (optional) - domain used to load hCaptcha interface, defaults to hcaptcha.com
  • user_agent (optional) - user-agent used to load captcha interface
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 31,
    "status": "submitted"
}

Retrieve

GET https://bcsapi.xyz/api/captcha/{HCAPTCHA_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • hcaptcha_id - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
    "id":31,
    "solution": "PmL43f64f1zc...z3fpclM",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
    "resp_key": "E0_eyJ0eXAiOiJ...BGLVe0IisJQ0",
    "status":"completed"
}

Use the data inside the solution object in order to bypass the page with hCaptcha

Note

Some websites require the same user_agent to be used. In certain cases resp_key is also required for verification.

FunCaptcha (Arkose Labs)

Required parameters for solving through bestcaptchasolver service:

  • page_url
  • s_url
  • site_key

Submit

POST https://bcsapi.xyz/api/captcha/funcaptcha

Body paramaters:

{
    "page_url":"http://website.com",
    "s_url":"https://api.arkoselabs.com",
    "site_key":"11111-11..-11-11111",
    "access_token": "your_access_token"
}
  • access_token - user's access token
  • page_url - page / domain on which you encountered the captcha
  • s_url - API / source URL for funcaptcha
  • site_key - sitekey for captcha, can be gathered from source / DOM of page
  • data (optional) - extra data in JSON format, used in loading FunCaptcha
  • user_agent (optional) - user-agent used to load captcha interface
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 31,
    "status": "submitted"
}

Retrieve

GET https://bcsapi.xyz/api/captcha/{FUNCAPTCHA_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • funcaptcha_id - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
    "id":31,
    "solution": "56460421add...|surl=https://api.arkoselabs.com",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
    "status":"completed"
}

Turnstile (Cloudflare)

Required parameters for solving through bestcaptchasolver service:

  • page_url
  • site_key

Submit

POST https://bcsapi.xyz/api/captcha/turnstile

Body paramaters:

{
    "page_url":"http://website.com",
    "site_key":"0x4AAAAAAABfevQ3vMbx22CS",
    "access_token": "your_access_token"
}
  • access_token - user's access token
  • page_url - page / domain on which you encountered the captcha
  • site_key - sitekey for captcha, can be gathered from source / DOM of page
  • action (optional) - gathered from source / DOM of page
  • cdata (optional) - gathered from source / DOM of page
  • domain (optional) - domain used to load turnstile interface, defaults to challanges.cloudflare.com
  • user_agent (optional) - user-agent used to load captcha interface
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 31,
    "status": "submitted"
}

Retrieve

GET https://bcsapi.xyz/api/captcha/{TURNSTILE_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • turnstile_id - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
    "id":31,
    "solution": "0.of1fYQaO...378d3f8efa",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36",
    "status":"completed"
}

Task

Required parameters for solving through bestcaptchasolver service:

  • template_name
  • page_url
  • variables

Submit

POST https://bcsapi.xyz/api/captcha/task

Body paramaters:

{
  "template_name": "Login test page",
  "page_url": "https://bestcaptchasolver.com/automation/login",
  "variables": {
    "username": "test",
    "password": "hardToGuess"
  },
  "access_token": "your_access_token"
}
  • access_token - user's access token
  • template_name - the name of the template
  • page_url - page URL / link where template will be executed
  • variables - variables that are used in the template execution
  • user_agent (optional) - user-agent used to load the task
  • proxy (optional) - a proxy in the format of 12.34.56.78:8080 or user:[email protected]:8080 if it requires authentication
  • proxy_type (optional) - goes with proxy parameter, and for now it can be only HTTP because we support only this type of proxies currently
  • affiliate_id (optional) - ID of affiliate check /partner page

Returns

{
    "id": 31,
    "status": "submitted"
}

Push variables

Update task variables while it is being solved by the worker. Useful when dealing with data / variables, of which value you don't know, only after a certain step or action of the task. For example, in websites that require 2 factor authentication code.

When the task (while running on workers machine) is getting to an action defined in the template, that requires a variable, but variable was not set with the task submission, it will wait until the variable is updated through push.

Required parameters:

  • id
  • pushVariables
  • access_token - user's access token

POST https://bcsapi.xyz/api/captcha/task/pushVariables/{TASK_ID}

Body paramaters:

{
  "pushVariables": {
    "tfa_code": "1304"
  },
  "access_token": "your_access_token"
}
  • task_id - the ID of task captcha received on submission
  • pushVariables - JSON or JSON stringified pushVariables
  • access_token - user's access token

Returns

{
    "status": "updated"
}

Multiple variables or single variable can be updated through one request.

The endpoint can be used as many times as it is required per captchaID.

Retrieve

GET https://bcsapi.xyz/api/captcha/{TASK_ID}?access_token={ACCESS_TOKEN}

Query parameters:

  • task_id - id received from submission
  • access_token - access token with which captcha information was submitted

Returns

{
  "id": 532423652,
  "solution": {
    "screenshots": [],
    "lastUrl": "https://bestcaptchasolver.com/account",
    "lastScreenshot": "https://bestcaptchasolver.com/task-screenshot/20e5...5823/last.jpg",
    "localStorage": {
      "_grecaptcha": "09AOR1k1A6J...Un54sp11NVHtO21b10g"
    },
    "cookies": [
      {
        "domain": "bestcaptchasolver.com",
        "hostOnly": true,
        "httpOnly": false,
        "name": "user",
        "path": "/automation",
        "sameSite": "unspecified",
        "secure": false,
        "session": true,
        "storeId": "0",
        "value": "test"
      }
    ],
    "fingerprint": {
      "userAgent": "Mozilla/5.0 (Linux; Android 8.1.0; CPH1853 Build/OPM1.171019.026; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/93.0.4577.82 Mobile Safari/537.36",
      "screen": {
        "height": 1080,
        "width": 1920,
        "availHeight": 1048,
        "availWidth": 1920,
        "pixelDepth": 24,
        "colorDepth": 24,
        "availLeft": 0,
        "availTop": 32
      }
    }
  },
  "status": "completed"
}

Set captcha bad

Use it in case our service solved the captcha but it was incorrect

POST https://bcsapi.xyz/api/captcha/bad/{CAPTCHA_ID}

Query parameters:

  • captcha_id - is the captcha ID of the the captcha which was completed incorrectly

Body parameters

{"access_token": "FFB0BF8905CA4AD992C8BE256F35682F"}
  • access_token - access_token with which captcha was submitted

Returns

{
    "id": 53,
    "status": "updated"
}

or

{
    "id": 53,
    "status": "set to bad already"
}

Errors

  • invalid or missing access key
    {
       "status": "error",
       "message": "access token is invalid or missing"
    }
  • wrong/non-existent access key
    {
    "status": "error",
    "message": "authentication failed"
    }
  • solving of captcha timeout out
    {
       "status": "error",
       "message": "timed out"
    }
  • no captcha with given ID
    {
      "status": "error",
      "message": "no captcha with given ID"
    }

Observations

The root endpoint for the API is located at https://bcsapi.xyz/api

If, for some reason you can't access the bcsapi.xyz domain, you will be able to change the root endpoint of the API to https://bestcaptchasolver.com/api

No other changes required.

2captcha,DBC and anticaptcha API support

We've designed a captcha gate, which allows you to redirect traffic from other captcha services through bestcaptchasolver. Currently, we've integrated the following services:

  • 2captcha.com
  • deathbycaptcha.com
  • anti-captcha.com

Redirection

The gates are redirecting the following actions to our service:

  • get balance
  • submit image captcha
  • retrieve image captcha
  • submit recaptcha
  • retrieve recaptcha response

In other words, if you have software that works with any of the above services, using the gate will allow you to use our service, with the same software to bypass all your captchas.

This is achieved by running a batch program, that writes config information into the hosts file of the Windows operating system. All this is done automatically, all you have to do is run it. For linux, we have a python script that allows you to toggle (enable / disable) a pair of IP DOMAIN

The last step, is to use replace access token OR username & password with credentials from /account. In this way, the programs will run even though they were built for one of the services above, but in reality our service will be used for completion.

In case you don't want to use the gate anymore, you can edit the hosts file which is located here: %SystemRoot%\System32\drivers\etc\hosts

On linux, you'll find the hosts file in /etc/hosts

Both operating systems require admin / root access in order to modify the files

For more details about the hosts file check this link

Installation

Clone the github repository git clone https://github.com/bestcaptchasolver/gates

Once you got it, go to scripts/windows folder, and run bat file for the service you want to redirect

It will ask you for administrator rights, because it's writing to a system file, allow it, and the gate should be enabled within few seconds

For linux, here's the usage of the script: ./linux_hosts.py 127.0.0.1 site.com which can be found in scripts/linux

View on github >

Download >