Server-side Validation
You will need an API key to prove it's you, you can create one on the API Keys page in the dashboard.
To verify the CAPTCHA solution, make a POST request to https://api.friendlycaptcha.com/api/v1/siteverify
with the following parameters:
POST Parameter | Description |
---|---|
solution | The solution value that the user submitted in the frc-captcha-solution field |
secret | An API key that proves it's you, create one on the Friendly Captcha website |
sitekey | Optional: the sitekey that you want to make sure the puzzle was generated from. |
You can pass these parameters in a JSON body, or as formdata.
If your account is on the Advanced or Enterprise plan your server can also make a request to our EU endpoint.
The verification response
The response will tell you whether the CAPTCHA solution is valid and hasn't been used before. The response body is a JSON object:
{
"success": true|false,
"errors": [...] // optional
}
If success
is false, errors
will be a list containing at least one of the following error codes below. If you are seeing status code 400 or 401 your server code is probably not configured correctly.
Error code | Status | Description |
---|---|---|
secret_missing | 400 | You forgot to add the secret (=API key) parameter. |
secret_invalid | 401 | The API key you provided was invalid. |
solution_missing | 400 | You forgot to add the solution parameter. |
bad_request | 400 | Something else is wrong with your request, e.g. your request body is empty. |
solution_invalid | 200 | The solution you provided was invalid (perhaps the user tried to tamper with the puzzle). |
solution_timeout_or_duplicate | 200 | The puzzle that the solution was for has expired or has already been used. |
⚠️ Status code 200 does not mean the solution was valid, it just means the verification was performed succesfully. Use the
success
field.
A solution can be invalid for a number of reasons, perhaps the user submitted before the CAPTCHA was completed or they tried to change the puzzle to make it easier. The first case can be prevented by disabling the submit button until the CAPTCHA has been completed succesfully.
Verification Best practices
If you receive a response code other than 200 in production, you should probably accept the user's form despite not having been able to verify the CAPTCHA solution.
Maybe your server is misconfigured or the Friendly Captcha servers are down. While we try to make sure that never happens, it is a good idea to assume one day disaster will strike.
An example: you are using Friendly Captcha for a sign up form and you can't verify the solution. It is better to trust the user and let them sign up anyway, because otherwise no signup will be possible at all. Do send an alert to yourself!