Reference

Server verification

The widget only proves that a browser did the work. Your server decides whether to trust the submission by exchanging the one-time token for a result. This is the one call every integration has to make, and it must happen on the server.

Endpoint

POST https://www.proofval.com/v1/verify
PartValue
Header X-Secret-KeyYour site's secret key. Required.
Header Content-Typeapplication/json
Body{"token": "..."} — the value of the proofval-token form field.
HTTP
POST /v1/verify HTTP/1.1
Host: www.proofval.com
Content-Type: application/json
X-Secret-Key: YOUR_SECRET_KEY

{"token": "TOKEN_FROM_FORM"}

Response

A successful verification returns HTTP 200 with:

JSON
{"success": true}

Anything else means the submission must be rejected. A rejected token also returns HTTP 200, with success: false and a human-readable error. Authentication, request and limit problems use 4xx status codes and, where you may want to branch on them, a stable code:

JSON
{"success": false, "error": "Token already used"}

{
  "success": false,
  "error": "Too many verification requests. Please slow down.",
  "code": "rate_limited"
}

Error reference

StatuserrorcodeMeaning
200Token not found—The token was never issued for this site. Check that the secret key belongs to the same site as the widget's site key.
200Token already used—Tokens are single-use. A second verify call for the same token always fails. Make sure you call verify exactly once per submission.
200Token expired—More than 15 minutes passed between verification in the browser and your call. Ask the visitor to verify again.
400Missing token—The body had no token. Usually the hidden field was not posted, for example because the form was serialised before the widget verified.
401Missing secret key—No X-Secret-Key header.
401Invalid secret key—The key does not match an active site.
429Too many verification requests.rate_limitedMore than 20 verify calls in one minute for this site. Retry shortly; if you hit this in normal traffic, contact us.
429Monthly verification limit reached.quota_exceededThe site's plan quota is used up for the month. The widget shows the same condition to visitors. Upgrade the plan in the dashboard.

Examples

curl
curl -X POST https://www.proofval.com/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-Secret-Key: YOUR_SECRET_KEY" \
  -d '{"token": "TOKEN_FROM_FORM"}'

Rules of thumb

Limits

LimitValueWhat happens
Token lifetime15 minutes"Token expired" after that.
Token uses1"Token already used" on the second call.
Verify calls per site20 per minuteHTTP 429 with rate_limited.
Verifications per monthDepends on planHTTP 429 with quota_exceeded; the widget shows the quota state to visitors.
Sites per accountFree: 1 · Starter: 1 · Basic: 5 · Growth: unlimitedThe dashboard refuses to create another site until you upgrade. Existing sites are unaffected.