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
| Part | Value |
|---|---|
Header X-Secret-Key | Your site's secret key. Required. |
Header Content-Type | application/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
| Status | error | code | Meaning |
|---|---|---|---|
| 200 | Token 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. |
| 200 | Token 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. |
| 200 | Token expired | — | More than 15 minutes passed between verification in the browser and your call. Ask the visitor to verify again. |
| 400 | Missing token | — | The body had no token. Usually the hidden field was not posted, for example because the form was serialised before the widget verified. |
| 401 | Missing secret key | — | No X-Secret-Key header. |
| 401 | Invalid secret key | — | The key does not match an active site. |
| 429 | Too many verification requests. | rate_limited | More than 20 verify calls in one minute for this site. Retry shortly; if you hit this in normal traffic, contact us. |
| 429 | Monthly verification limit reached. | quota_exceeded | The 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"}'
PHP
<?php
function proofvalVerify(string $token): bool
{
if ($token === '') {
return false;
}
$ch = curl_init('https://www.proofval.com/v1/verify');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-Secret-Key: ' . getenv('PROOFVAL_SECRET_KEY'),
],
CURLOPT_POSTFIELDS => json_encode(['token' => $token]),
]);
$raw = curl_exec($ch);
curl_close($ch);
if ($raw === false) {
return false; // network error: fail closed
}
$body = json_decode($raw, true);
return ($body['success'] ?? false) === true;
}
if (! proofvalVerify($_POST['proofval-token'] ?? '')) {
http_response_code(400);
exit('Please complete the verification step.');
}
PHP (Symfony HttpClient)
<?php
namespace App\Service;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class ProofvalVerifier
{
public function __construct(
private readonly HttpClientInterface $httpClient,
private readonly string $proofvalSecretKey, // bind to %env(PROOFVAL_SECRET_KEY)%
) {
}
public function verify(?string $token): bool
{
$token = trim((string) $token);
if ($token === '') {
return false;
}
try {
$response = $this->httpClient->request('POST', 'https://www.proofval.com/v1/verify', [
'headers' => ['X-Secret-Key' => $this->proofvalSecretKey],
'json' => ['token' => $token],
'timeout' => 5,
]);
// 200 with success:false for bad tokens, 4xx for auth/limits: read both.
$data = $response->toArray(false);
} catch (ExceptionInterface) {
return false;
}
return ($data['success'] ?? false) === true;
}
}
// In a controller, after $form->isValid():
// if (! $verifier->verify($request->request->get('proofval-token'))) {
// $form->addError(new FormError('Please complete the verification step.'));
// }
Node.js
export async function proofvalVerify(token) {
if (!token) return false;
try {
const response = await fetch('https://www.proofval.com/v1/verify', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Secret-Key': process.env.PROOFVAL_SECRET_KEY,
},
body: JSON.stringify({ token }),
signal: AbortSignal.timeout(5000),
});
const result = await response.json();
return result.success === true;
} catch {
return false; // network error: fail closed
}
}
// Express:
// if (!(await proofvalVerify(req.body['proofval-token']))) {
// return res.status(400).send('Please complete the verification step.');
// }
Python (requests)
import os
import requests
def proofval_verify(token: str) -> bool:
if not token:
return False
try:
response = requests.post(
"https://www.proofval.com/v1/verify",
json={"token": token},
headers={"X-Secret-Key": os.environ["PROOFVAL_SECRET_KEY"]},
timeout=5,
)
return response.json().get("success") is True
except (requests.RequestException, ValueError):
return False # network or parse error: fail closed
# Django:
# if not proofval_verify(request.POST.get("proofval-token", "")):
# return HttpResponseBadRequest("Please complete the verification step.")
#
# Flask:
# if not proofval_verify(request.form.get("proofval-token", "")):
# abort(400)
Rules of thumb
- Always verify on the server. The secret key must never reach the browser, and a client-side check can be skipped by any bot.
- Fail closed. Network errors, timeouts, malformed responses and
success: falseall mean "reject". The examples above do this. - Verify once per submission. Tokens are single-use, so do not call verify in a validation pass and again when saving.
- Verify promptly. Tokens expire 15 minutes after the visitor verified. Do not queue the check for later.
- Keep a short timeout. Five seconds is plenty. A slow verify should not hang your form handler.
- Match the keys. The secret key you verify with must belong to the same site as the site key on the widget, or you get "Token not found".
Limits
| Limit | Value | What happens |
|---|---|---|
| Token lifetime | 15 minutes | "Token expired" after that. |
| Token uses | 1 | "Token already used" on the second call. |
| Verify calls per site | 20 per minute | HTTP 429 with rate_limited. |
| Verifications per month | Depends on plan | HTTP 429 with quota_exceeded; the widget shows the quota state to visitors. |
| Sites per account | Free: 1 · Starter: 1 · Basic: 5 · Growth: unlimited | The dashboard refuses to create another site until you upgrade. Existing sites are unaffected. |