VerifyRelay

Documentation

One endpoint to send, two webhook receivers, one health check. Base URL defaults to http://localhost:8080.

AuthenticationSend your key in the X-API-Key header on POST /v1/verify/send. GET /v1/health is public. Webhook endpoints are verified by provider signatures, not your API key.

Quickstart

  1. Send a verification code

    One POST. The router picks the best-scoring provider; the response shows every attempt.

    curl -X POST http://localhost:8080/v1/verify/send \
  -H "X-API-Key: $VERIFYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15551234567", "code": "482913"}'

# {"verification_id": "vr_...", "status": "delivered",
#  "provider": "twilio", "attempts": 1, "cost_usd": 0.0083}

  2. Enable escalation

    Add "escalate": true to fall back SMS → voice → WhatsApp automatically when SMS fails across all routes.

    curl -X POST http://localhost:8080/v1/verify/send \
  -H "X-API-Key: $VERIFYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15551234567", "code": "482913", "escalate": true}'

  3. Point your provider webhooks at us

    Set your Twilio status-callback and Vonage DLR URLs to /v1/webhooks/twilio and /v1/webhooks/vonage. Twilio signatures are verified automatically when your auth token is configured.

  4. Check health

    Liveness plus current per-route delivery scores.

    curl http://localhost:8080/v1/health

API reference

MethodEndpointWhat it does
POST/v1/verify/sendSend OTP/transactional SMS. Fields: to (E.164), code or message, escalate. API-key auth.
POST/v1/webhooks/twilioTwilio status-callback ingestion (form-encoded). Signature-verified when TWILIO_AUTH_TOKEN is set.
POST/v1/webhooks/vonageVonage DLR ingestion (form-encoded). Signature verification is roadmap — IP-allowlist recommended.
GET/v1/healthLiveness + per-route delivery scores, including whether a real SMS provider is configured. Public.
POST/v1/stripe/webhookStripe provisioning webhook (signature-verified; answers 503 until configured).
POST/v1/claimExchange a Stripe checkout session id for your API key — exactly once, via claim.html.
POST/v1/signup/freeCreate a small free tenant (100 verifications/mo, single route).
GET/v1/usageYour monthly verifications, included allowance, and metered overage ($0.02/verification beyond cap). API-key auth.

Full reference with request/response examples ships in the repo as OPENAPI.md.

Need a hand?

Email us with what you're building.

Contact us
Activation status (honest, October 2026): VerifyRelay’s routing, failover, metering and self-serve provisioning software is built and tested, and checkout provisions an API key via the claim page. Live SMS delivery is not available yet: it starts only after a messaging provider account (Twilio or Vonage) is configured on the deployment and US 10DLC registration is complete. Until then the API answers sends with an explicit provider_not_configured response — no message is sent and no delivery is claimed.