Siteverify API

The siteverify API is the API used to verify CAPTCHA solutions.

It lives on /api/v0/siteverify of your designated hostname (eg https://global.captcha.party/api/v0/siteverify).

The API only accepts POST requests, with either a JSON or formdata body.

Note

Enterprise customers can make use of Offline Verification to validate solutions without calling the siteverify API.

Request payload

The following arguments are allowed:

Name	Required	Description
solution	yes	the solution to verify
secret	yes	your secret
remoteip	no	ip of the user
useragent	no	user agent of the user

remoteip

The remoteip argument is used to verify the user’s IP address matches the one which was used to solve the challenge. This is useful to prevent CAPTCHA farms.

Response payload

The response is a JSON object which is either a success or fail. The response payload will always have the success field.

Success payload

If the success field is true, then the response has the following shape:

Hobby plan

{
    "success": true,
    "timestamp": 1672527600,
    "hostname": "example.com",
}

Professional plan

{
    "success": true,
    "timestamp": 1672527600,
    "hostname": "example.com",
    "data": "customerid=1234",
}

Business plan

{
    "success": true,
    "timestamp": 1672527600,
    "hostname": "example.com",
    "data": "customerid=1234",
    "action": "login",
}

Enterprise plan

{
    "success": true,
    "timestamp": 1672527600,
    "hostname": "example.com",
    "data": "customerid=1234",
    "action": "login",
    "checks": [],
    "kind": null,
}

The timestamp is a UNIX timestamp of when the widget started executing the challenge.

Failure payload

If the success field is false, then the response includes an additional errors field which is a list of error codes.

Hobby plan

{
    "success": false,
    "errors": ["..."],
    "timestamp": 1672527600,
    "hostname": "example.com",
}

Professional plan

{
    "success": false,
    "errors": ["..."],
    "timestamp": 1672527600,
    "hostname": "example.com",
    "data": "customerid=1234",
}

Business plan

{
    "success": false,
    "errors": ["..."],
    "timestamp": 1672527600,
    "hostname": "example.com",
    "data": "customerid=1234",
    "action": "login",
}

Enterprise plan

{
    "success": false,
    "errors": ["..."],
    "timestamp": 1672527600,
    "hostname": "example.com",
    "data": "customerid=1234",
    "action": "login",
    "checks": ["..."],
    "kind": "...",
}

Note

The fields timestamp, hostname, action, data and checks are only available on the following error codes: expired-solution, replayed-solution, mismatched-remoteip, mismatched-useragent, and automation-detected.

5xx responses and non-JSON content

If you receive a non-JSON response or 5xx status code, you should retry the request a few times with a few seconds delay.

If you are still unable to receive a response by our servers after a few retries, you need to make a decision of whether to fail open or fail closed.

If you are encoutering frequent errors, please consult our status page and contact support.

Ratelimits

Captcha.party has a ratelimit of 100 requests per 10 seconds per IP. This limit does not differentiate between valid and invalid requests. If you exceed this limit, you will be blacklisted for 10 seconds and see a 429 response.

Consider using Offline Validation to reduce invalid requests.

Error codes

When the success field is false, the response payload will contain the errors field which is an array of error codes. You can find the meaning of each error-code in the table below:

Error Code	Description
bad-request	the request was invalid or malformed
missing-input-solution	the solution field was missing in the request
missing-input-secret	the secret field was missing in the request
invalid-input-solution	the solution field was invalid
invalid-input-secret	the secret field was invalid
invalid-input-remoteip	the remoteip field was invalid
mismatched-sitekey	the solution and secret do not belong to the same sitekey
invalid-hostname	the /siteverify API is called on the wrong hostname
expired-solution	the provided solution expired
replayed-solution	the provided solution is replayed (was redeemed before)
mismatched-remoteip	the provided remoiteip and actual do not match
mismatched-useragent	the provided useragent and actual do not match
automation-detected	we detected the usage of automation software
ratelimit-exceeded	you exceeded the ratelimit
internal-error	an internal error occured