Siteverify API

Use the official SDK when possible. Direct HTTP integration is available for other server runtimes.

Endpoint

POST https://humanpass.valgix.com/v1/siteverify
Authorization: Bearer hp_secret_live_REPLACE_ME
Content-Type: application/json

This endpoint is server-to-server only. Never call it from browser code.

Request

{
  "response": "hp_response_...",
  "remoteip": "203.0.113.10",
  "idempotency_key": "signup-request-01HXYZ"
}

Field	Required	Description
response	Yes	Opaque token returned by the widget.
remoteip	No	IP observed by your backend. IPv4 or IPv6.
idempotency_key	No	8–128 characters from A-Z, a-z, 0-9, ., _, ~, or -.

Successful verification

{
  "success": true,
  "challenge_ts": "2026-08-23T12:00:00.000Z",
  "hostname": "app.example.com",
  "action": "signup",
  "sitekey": "hp_site_live_...",
  "environment": "live",
  "verification_id": "hpv_..."
}

Compare hostname, action, sitekey, and environment with the values expected by your application before continuing.

Semantic failure

{
  "success": false,
  "error_codes": ["timeout_or_duplicate"],
  "request_id": "..."
}

The response token is single-use. Obtain a fresh browser response after a semantic failure unless you are safely retrying the exact same request with the same idempotency key.

HTTP status behavior

Status	Meaning
200	Verification completed; inspect success.
400	Missing or malformed response input.
401	Secret key is missing or invalid.
429	Rate limited; respect Retry-After.
503	Verification security state is temporarily unavailable.
500	Unexpected service failure; record the request ID and fail closed.

cURL example

curl https://humanpass.valgix.com/v1/siteverify \
  --request POST \
  --header "Authorization: Bearer $HUMANPASS_SECRET_KEY" \
  --header "Content-Type: application/json" \
  --data '{"response":"hp_response_REPLACE_ME"}'