Skip to Content
Getting Started3. Verify the Response

3. Verify the Response

Before your server processes the form, it sends the response token to CaptchaFox to check that it’s valid. This is what keeps bots out: they can send requests to your server without ever loading the widget.

Make the verification request

Send a POST request with the application/x-www-form-urlencoded content type to:

https://api.captchafox.com/siteverify
ParameterRequiredDescription
secretYesThe secret key of your site.
responseYesThe response token from the form field cf-captcha-response.
sitekeyNoYour sitekey. Recommended.
remoteIpNoThe visitor’s IP address. Must match the IP that solved the challenge.

Each token can be verified once and is valid for 2 minutes. You can extend this in the portal.

Use the @captchafox/node  library:

npm install @captchafox/node
import { verify } from '@captchafox/node'; const result = await verify(process.env.CAPTCHAFOX_SECRET, req.body['cf-captcha-response'], { sitekey: 'YOUR_SITEKEY', remoteIp: req.ip, // optional }); if (!result.success) { // Reject the request }

More libraries are listed under Server integrations.

Response

The API responds with a JSON object:

FieldTypeDescription
successbooleanWhether the token is valid. Always check this field: failed verifications also return status 200.
challenge_tsstringISO timestamp of the challenge (yyyy-MM-dd'T'HH:mm:ssZZ). Only included on success.
hostnamestringHostname of the site where the challenge was solved. Optional.
error-codesstring[]Why the verification failed. Only included if success is false. See Error codes.
insightsobjectVerification details. Enterprise plans only.
{ "success": true, "challenge_ts": "2026-11-20T10:15:30+00:00", "hostname": "example.com" }

Error codes

Error CodeDescription
missing-input-secretThe secret parameter is missing.
invalid-input-secretThe secret parameter is invalid or malformed.
missing-input-responseThe response parameter is missing.
invalid-input-responseThe response parameter is invalid or malformed.
bad-requestThe request is invalid or malformed.
timeout-or-duplicateThe token has expired or was already verified.
invalid-ip-matchThe IP address does not match the remoteIp parameter.

Common causes of failed verifications

  • Verified twice: tokens are single-use. If the user has to resubmit the form, call captchafox.reset() to get a new token.
  • Expired: the user waited too long before submitting.
  • Keys don’t match: the sitekey and secret key must belong to the same site.
  • Wrong IP: behind a proxy, remoteIp must be the visitor’s IP. If unsure, leave it out.

Handling outages

Set a timeout of a few seconds on the request. If CaptchaFox can’t be reached (network error, timeout or 5xx status), you can let the request through so your form keeps working, and log it. Never do this when the API responds with success: false or a 4xx status.

Go-live checklist

  • Replace the test keys with your real keys.
  • Every protected request is verified on the server and rejected if verification fails.
  • The secret key is only stored on your server.
  • Your Content Security Policy allows CaptchaFox, if you use one.
  • If you use Hidden Mode, the privacy notice is on the page.
Last updated on