Skip to content
REST · JSON · HMAC-signed webhooks

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_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep keys on your server. Never ship them in a mobile app or browser bundle.

Create a verification

POST /v1/verifications

user_phonerequiredstringThe number to verify. E.164 (+919876543210) preferred; 10-digit Indian numbers are accepted.
referencestringYour own ID (max 128 chars), echoed back in responses and webhooks.
webhook_urlstringOverrides your account webhook URL for this verification only.
Request
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"
  }'
201 Created
{
  "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:

HTML
<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:

POST to your webhook URL
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 2xx within 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 id or the verification id.
  • 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.

Node.js
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));
}
Python
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"])
Go
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." } }
400invalid_jsonBody is not valid JSON.
401unauthorizedMissing, invalid or revoked API key.
404not_foundVerification does not exist or belongs to another account.
422invalid_phone / invalid_webhook_url / invalid_inputValidation failed.
429rate_limitedSlow down; see Retry-After.
503no_capacityNo 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.