API documentation
Base URL: https://api.verifynumber.in/v1. Requests and responses are JSON. Times are UTC in RFC 3339 format.
Overview
A verification has four states:
pending: waiting for the user to send the SMS.verified: we received the code from the user's number on the assigned line before expiry.expired: no matching SMS arrived in time (default 10 minutes).failed: the assigned receiving line went out of service before the user sent the SMS. Start a new verification.
A message counts only if all of these hold: the sender equals user_phone (normalised to E.164), the body contains the code, it arrived on the number in send_to, and it was received before expires_at.
Authentication
Create an API key in the dashboard and send it as a bearer token. Keys start with vn_live_ and are shown once; we only store a hash.
Authorization: Bearer vn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeep keys on your server. Never ship them in a mobile app or browser bundle.
Create a verification
POST /v1/verifications
| user_phonerequired | string | The number to verify. E.164 (+919876543210) preferred; 10-digit Indian numbers are accepted. |
| reference | string | Your own ID (max 128 chars), echoed back in responses and webhooks. |
| webhook_url | string | Overrides your account webhook URL for this verification only. |
curl -X POST https://api.verifynumber.in/v1/verifications \
-H "Authorization: Bearer $VERIFYNUMBER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"user_phone": "+919876543210",
"reference": "signup-8812"
}'{
"id": "vrf_4d66wzrknbkm2yjoccpx",
"status": "pending",
"user_phone": "+919876543210",
"send_to": "+919000000001",
"message": "VERIFY 794980",
"sms_link": "sms:+919000000001?body=VERIFY%20794980",
"reference": "signup-8812",
"expires_at": "2026-11-19T07:27:27.962Z",
"verified_at": null,
"created_at": "2026-11-19T07:17:27.961Z"
}If no receiving number is available right now you get 503 no_capacity. Retry with a short backoff.
Retrieve a verification
GET /v1/verifications/{id}. Use this if you prefer polling to webhooks, or to double-check before granting access.
curl https://api.verifynumber.in/v1/verifications/vrf_4d66wzrknbkm2yjoccpx \
-H "Authorization: Bearer $VERIFYNUMBER_API_KEY"Showing the step to your user
Show the exact message and number, plus a button that opens the messaging app pre-filled:
<p>Send <b>VERIFY 794980</b> to <b>+91 90000 00001</b> from +91 98765 43210</p>
<a href="sms:+919000000001?body=VERIFY%20794980">Open messages</a>On Android you can launch an ACTION_SENDTO intent with the sms_link. Remind users to send from the SIM that holds the number being verified (dual-SIM phones may default to the other one).
Webhooks
Set a webhook URL in the dashboard. We POST an event when a verification becomes verified, expired or failed:
X-VerifyNumber-Event: verification.verified
X-VerifyNumber-Delivery: 10293
X-VerifyNumber-Signature: t=1795072648,v1=845b3ff0949712bc5e7410...
Content-Type: application/json
{
"id": "evt_i5rzcos3cjve7w2q44fn",
"type": "verification.verified",
"created_at": "2026-11-19T07:17:28.032Z",
"data": { "id": "vrf_4d66wzrknbkm2yjoccpx", "status": "verified", "...": "..." }
}- Respond with any
2xxwithin 10 seconds. Anything else counts as a failure. - Failures are retried with exponential backoff (30s, 1m, 2m, 4m, … capped at 6h) for up to 12 attempts.
- Every attempt is recorded, with its status code and response, in Dashboard → Webhooks, where you can also replay it.
- Delivery is at-least-once. Deduplicate on the event
idor the verificationid. - Redirects are not followed. Use HTTPS.
Verifying signatures
Compute HMAC-SHA256(secret, t + "." + raw_body) with your webhook secret (from the dashboard) and compare it with v1 in constant time. Reject timestamps older than 5 minutes.
import crypto from "node:crypto";
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret)
.update(parts.t + "." + rawBody).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}import hmac, hashlib, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
mac = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256)
fresh = abs(time.time() - int(parts["t"])) < 300
return fresh and hmac.compare_digest(mac.hexdigest(), parts["v1"])func verify(body []byte, header, secret string) bool {
var ts, sig string
for _, p := range strings.Split(header, ",") {
k, v, _ := strings.Cut(p, "=")
if k == "t" { ts = v } else if k == "v1" { sig = v }
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(ts + "."))
mac.Write(body)
return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(sig))
}Errors
Errors use standard HTTP status codes and a consistent body:
{ "error": { "code": "invalid_phone", "message": "user_phone is not a valid phone number." } }| 400 | invalid_json | Body is not valid JSON. |
| 401 | unauthorized | Missing, invalid or revoked API key. |
| 404 | not_found | Verification does not exist or belongs to another account. |
| 422 | invalid_phone / invalid_webhook_url / invalid_input | Validation failed. |
| 429 | rate_limited | Slow down; see Retry-After. |
| 503 | no_capacity | No receiving number is online. Retry shortly. |
Rate limits
Default limit is 50 requests per second per account, with bursts up to 100. Contact us if you need more.