WhatsApp Verification API
Verify a phone number with two REST calls and one message from the user. You show a link or QR code, the user sends a pre-filled WhatsApp message, and you receive the number WhatsApp already verified. There is no code to send, type, intercept or pump.
- POST
/start-verification200 - WAIT
user sends one message0 codes - HOOK
verification_successverified
You need an API key. Create an account, finish onboarding for 100 free credits, then copy a key from API keys.
The base URL is https://api.phone-verif.com.
Call POST /start-verification from your server. Send a unique session_id and the callback_url the user returns to.
curl -X POST https://api.phone-verif.com/start-verification \
-H "x-api-key: $PHONE_VERIF_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"session_id": "order-4821",
"callback_url": "https://your-app.example/verified"
}'const response = await fetch('https://api.phone-verif.com/start-verification', {
method: 'POST',
headers: {
'x-api-key': process.env.PHONE_VERIF_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
session_id: crypto.randomUUID(),
callback_url: 'https://your-app.example/verified',
}),
});
if (!response.ok) throw new Error(`Phone-Verif returned ${response.status}`);
const { session, whatsapp } = await response.json();import os
import uuid
import requests
response = requests.post(
"https://api.phone-verif.com/start-verification",
headers={"x-api-key": os.environ["PHONE_VERIF_API_KEY"]},
json={
"session_id": str(uuid.uuid4()),
"callback_url": "https://your-app.example/verified",
},
timeout=10,
)
response.raise_for_status()
data = response.json()
session, whatsapp = data["session"], data["whatsapp"]<?php
$ch = curl_init('https://api.phone-verif.com/start-verification');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_TIMEOUT => 10,
CURLOPT_HTTPHEADER => [
'x-api-key: ' . getenv('PHONE_VERIF_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'session_id' => bin2hex(random_bytes(16)),
'callback_url' => 'https://your-app.example/verified',
]),
]);
$data = json_decode(curl_exec($ch), true);
$deeplink = $data['whatsapp']['deeplink'];body, _ := json.Marshal(map[string]string{
"session_id": uuid.NewString(),
"callback_url": "https://your-app.example/verified",
})
req, _ := http.NewRequest("POST",
"https://api.phone-verif.com/start-verification", bytes.NewReader(body))
req.Header.Set("x-api-key", os.Getenv("PHONE_VERIF_API_KEY"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
return err
}
defer res.Body.Close()
var data struct {
Session struct{ ValidationToken string `json:"validation_token"` } `json:"session"`
WhatsApp struct{ Deeplink string `json:"deeplink"` } `json:"whatsapp"`
}
err = json.NewDecoder(res.Body).Decode(&data)Render whatsapp.deeplink as a QR code on desktop and as a button on mobile. The user opens WhatsApp, sends the pre-filled message and gets a confirmation with a link back to your callback_url.
{
"session": {
"session_id": "order-4821",
"validation_token": "xyz789",
"status": "pending",
"validity_timestamp": "2026-11-06T22:47:47.257Z"
},
"whatsapp": {
"number": "18073600555",
"deeplink": "https://t.phone-verif.com/qr/xyz789"
}
}Add a webhook URL in Settings and verify its signature. We POST the result as soon as the message arrives.
Your own number can be verified without spending credits. Register it in your profile, then run the whole flow as many times as you need. To see the flow first, try the demo.
{
"event": "verification_success",
"session_id": "order-4821",
"validation_token": "xyz789",
"status": "verified",
"validated_phone_number": "33612345678",
"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10"
}The message travels from the user to us, so nothing secret is sent to them. There is no code to phish, and no outbound SMS for fraudsters to pump.
- Your server starts a session and receives a link containing a one-time token.
- The user opens the link on their phone or scans it, then sends the pre-filled message.
- WhatsApp delivers that message with the sender's number, which WhatsApp has already verified.
- We match the token to your session and send you the result.
- The user returns to your
callback_urlwith?token=<validation_token>.
A session stays valid for 10 hours. Credits are spent when a verification completes, not when it starts, so an abandoned session costs nothing.
Send your API key in the x-api-key header on every call.
The ?key= query parameter works too, but URLs end up in logs and browser history. Use it for debugging only.
Keys belong on your server. Anyone holding a key can spend your credits, so never ship one to a browser or a mobile app. Your frontend calls your backend, and your backend calls this API.
x-api-key: YOUR_API_KEYwhatsapp.deeplink and whatsapp.qr_code_url go through our redirect, which records the scan and fills session.qr_code_scanned_at. whatsapp.direct_link opens WhatsApp directly and records nothing.
| Device | What to show |
|---|---|
| Desktop | A QR code of whatsapp.qr_code_url |
| Mobile | A button that opens whatsapp.deeplink |
Generate the QR code in your own frontend. Any QR library works, because the value is a plain URL.
import { QRCodeSVG } from 'qrcode.react';
export function VerifyPhone({ whatsapp }) {
const isMobile = /Android|iPhone|iPad/.test(navigator.userAgent);
return isMobile ? (
<a href={whatsapp.deeplink}>Verify with WhatsApp</a>
) : (
<QRCodeSVG value={whatsapp.qr_code_url} size={220} />
);
}Use webhooks as your source of truth. They arrive within seconds, and they work when the user never returns to your app.
Poll only on an explicit action, such as the user coming back to your page. When they land on your callback_url, read token from the query string and ask your backend to check it.
The token in that URL proves nothing by itself. Always confirm the session from your server with GET /check-verification-status before you trust it.
Treat both verified and sms_validated as success. A session that has expired answers 410.
app.get('/verified', async (req, res) => {
const url = new URL('https://api.phone-verif.com/check-verification-status');
url.searchParams.set('validation_token', req.query.token);
const response = await fetch(url, {
headers: { 'x-api-key': process.env.PHONE_VERIF_API_KEY },
});
if (!response.ok) return res.redirect('/verify?error=expired');
const { session } = await response.json();
const done = ['verified', 'sms_validated'].includes(session.status);
res.redirect(done ? '/welcome' : '/verify?pending=1');
});Every webhook carries an X-Webhook-Signature header: sha256= followed by the HMAC-SHA256 of the raw body, keyed with your webhook secret. Reject any request that fails the check.
- Fetch your secret once with
GET /webhook-secretand store it as a server-side secret. - Read the raw request body before any JSON parsing. Parsing and re-serializing changes the bytes.
- Compute the HMAC and compare it in constant time.
We retry once, after about 5 seconds, on a network error or a 5xx. Any other status counts as delivered, so answer 2xx quickly and do the work afterwards. A retry repeats the same event: use validation_token as your idempotency key. The age_verification_result event isn't retried.
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post('/webhooks/phone-verif',
express.raw({ type: 'application/json' }),
(req, res) => {
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.PHONE_VERIF_WEBHOOK_SECRET)
.update(req.body)
.digest('hex');
const received = req.get('X-Webhook-Signature') ?? '';
const valid = received.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) return res.sendStatus(401);
const event = JSON.parse(req.body);
res.sendStatus(200);
handleEvent(event); // Idempotent: keyed on event.validation_token
});import hashlib
import hmac
import os
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/webhooks/phone-verif")
def phone_verif_webhook():
raw = request.get_data()
digest = hmac.new(
os.environ["PHONE_VERIF_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256
).hexdigest()
received = request.headers.get("X-Webhook-Signature", "")
if not hmac.compare_digest(f"sha256={digest}", received):
abort(401)
handle_event(request.get_json()) # Idempotent: keyed on validation_token
return "", 200<?php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('PHONE_VERIF_WEBHOOK_SECRET'));
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (!hash_equals($expected, $received)) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
http_response_code(200);func webhook(w http.ResponseWriter, r *http.Request) {
raw, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "bad body", http.StatusBadRequest)
return
}
mac := hmac.New(sha256.New, []byte(os.Getenv("PHONE_VERIF_WEBHOOK_SECRET")))
mac.Write(raw)
expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(r.Header.Get("X-Webhook-Signature"))) {
w.WriteHeader(http.StatusUnauthorized)
return
}
w.WriteHeader(http.StatusOK)
}The flow parameter changes what a verification answers. Pass it in the query string or the JSON body of POST /start-verification.
flow | Use it for | You receive |
|---|---|---|
phone (default) | Proving a number | validated_phone_number and user_id |
login | Passwordless sign-in | user_id and is_new_user, no number |
2fa | Confirming a known user | match, no number |
age | Age checks | An age block, no number and no user_id |
user_id is a stable UUID for a given number and API key. Store it after the first verification. Unknown numbers on flow=login are registered automatically, with is_new_user: true.
flow=2fa requires user_id, which can be our UUID or your own linked ID. An unknown ID answers 404 before any session starts. If someone else replies, the session is still verified but match is false, so always check match.
login and 2fa hide the number by default. Add reveal=true to GET /check-verification-status to get it, for 1 credit on each call.
{
"event": "verification_success",
"session_id": "order-4821",
"status": "verified",
"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10",
"is_new_user": false
}{
"event": "verification_success",
"session_id": "order-4821",
"status": "verified",
"match": true
}curl -X POST https://api.phone-verif.com/start-verification \
-H "x-api-key: $PHONE_VERIF_API_KEY" \
-H "Content-Type: application/json" \
-d '{"flow": "2fa", "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10"}'flow=age verifies the phone number, then confirms the person's age through our age provider. Your account must have age verification configured, otherwise the call answers 503.
min_age sets the threshold, and defaults to your configured value or 18. reset=1 ignores an earlier pass for that number and runs the age check again.
You receive two webhooks, both signed with the same secret: verification_success with age.status: "pending", then age_verification_result once the provider answers. age.status ends as verified, denied or failed. While it is pending, links.age_verification in the status response takes the user straight to it.
curl -X POST "https://api.phone-verif.com/start-verification?flow=age&min_age=18" \
-H "x-api-key: $PHONE_VERIF_API_KEY"{
"event": "age_verification_result",
"session_id": "order-4821",
"validation_token": "xyz789",
"status": "verified",
"age": {
"status": "verified",
"verified": true,
"required": 18,
"verified_at": "2026-11-06T22:00:00.000Z",
"provider": "ageverif"
}
}Every session is open to WhatsApp, SMS and our bot, @PhoneVerif_com_bot, unless you send provider. The response carries a whatsapp, an sms and a telegram block, all with the same token. Show the links you want, and the first channel the user completes wins.
For Telegram, show telegram.deeplink as a QR code or a button. The user presses Start, then shares their own number with one tap. Typed numbers and other people's contacts are refused.
session.provider reads any until a channel completes the session, then whatsapp or telegram. An SMS completion reads whatsapp, with the status sms_validated. The other channel then refuses the token.
To lock a session to one channel, send provider:
| Value | Blocks returned | Token works on |
|---|---|---|
any (default) | whatsapp, sms, telegram | All three |
whatsapp | whatsapp, sms | WhatsApp and SMS. session.provider is absent. |
telegram | telegram | The bot |
Webhooks and status checks carry provider. When Telegram completes a flow=phone session they also carry the Telegram account: at the top level of the webhook, and in session.telegram in the status response. username and last_name can be null.
validated_phone_numberhas the same format as on WhatsApp, so a number gets the sameuser_idon both channels.- With
flow=age, the age link and result reach the user on the channel they finished on. - If Telegram is unavailable, the default opens a session without a
telegramblock, so check for it before showing it.provider=telegramanswers503withTELEGRAM_UNAVAILABLE: fall back by calling again withoutprovider.
curl -X POST https://api.phone-verif.com/start-verification \
-H "x-api-key: $PHONE_VERIF_API_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id": "order-4821", "provider": "telegram"}'{
"telegram": {
"bot_username": "PhoneVerif_com_bot",
"deeplink": "https://t.phone-verif.com/tg/xyz789",
"qr_code_url": "https://t.phone-verif.com/tg/xyz789",
"direct_link": "https://t.me/PhoneVerif_com_bot?start=xyz789"
}
}{
"event": "verification_success",
"session_id": "order-4821",
"validation_token": "xyz789",
"status": "verified",
"validated_phone_number": "33612345678",
"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10",
"provider": "telegram",
"telegram": {
"user_id": 123456789,
"username": "alice",
"first_name": "Alice",
"last_name": "Martin"
}
}Skip building a screen: start the session on your server, then load our page in an iframe or webview. It handles the QR code, the button and the live status.
https://phone-verif.com/verify?session_id=SESSION_ID&token=VALIDATION_TOKEN&embedded=true
| Parameter | Required | Description |
|---|---|---|
session_id | Yes | The ID you sent to /start-verification |
token | Yes | session.validation_token from the response |
embedded | No | true hides our header and footer |
The page sends a verification_complete message to its parent. Check event.origin, and use the message only to move your interface on: browser code can be forged, so confirm the result from your server or your webhook.
Use https://phone-verif.com/demo?embedded=true while you develop. It spends no credits.
<iframe
src="https://phone-verif.com/verify?session_id=SESSION_ID&token=TOKEN&embedded=true"
width="100%"
height="600"
style="border: 0"
title="Verify your phone number"
></iframe>
<script>
window.addEventListener('message', (event) => {
if (event.origin !== 'https://phone-verif.com') return;
if (event.data.type !== 'verification_complete') return;
// Refresh from your backend, which confirms the session.
location.reload();
});
</script>import { useEffect } from 'react';
export function PhoneVerification({ sessionId, token, onDone }) {
useEffect(() => {
const handler = (event) => {
if (event.origin !== 'https://phone-verif.com') return;
if (event.data.type === 'verification_complete') onDone();
};
window.addEventListener('message', handler);
return () => window.removeEventListener('message', handler);
}, [onDone]);
return (
<iframe
src={`https://phone-verif.com/verify?session_id=${sessionId}&token=${token}&embedded=true`}
width="100%"
height={600}
style={{ border: 0 }}
title="Verify your phone number"
/>
);
}// Fetch sessionId and token from your backend first.
val webView = findViewById<WebView>(R.id.webView)
webView.settings.javaScriptEnabled = true
webView.settings.domStorageEnabled = true
webView.loadUrl(
"https://phone-verif.com/verify?session_id=$sessionId&token=$token&embedded=true"
)// Fetch sessionId and token from your backend first.
let url = URL(string:
"https://phone-verif.com/verify?session_id=\(sessionId)&token=\(token)&embedded=true"
)!
let webView = WKWebView(frame: view.bounds)
view.addSubview(webView)
webView.load(URLRequest(url: url))These are the errors that break an integration most often.
| Don't | Do |
|---|---|
Send api_key in the JSON body of /start-verification | Use the x-api-key header. The body field is ignored and the call answers 400. |
| Call the API from a browser or mobile app | Call it from your server, and keep the key there. |
Read status at the top level of a response | Read session.status. Session fields live under session. |
Trust the token on your callback URL, or a postMessage | Confirm with GET /check-verification-status or a signed webhook. |
Wait for status: "expired" | Handle 410: an expired session answers with an error. |
Reuse a session_id | Generate a new one. Starting the same ID again cancels its previous token. |
Expect +33612345678 | validated_phone_number has digits only: 33612345678. |
Assume verified means the right person on flow=2fa | Check match. |
| Parse the webhook before checking the signature | Sign the raw bytes, then parse. |
- The API key is in a server-side secret, and appears in no client bundle.
callback_urlis set for every session, or a default is set in Settings.- A webhook URL is set in Settings, and its signature is verified.
- The webhook handler is idempotent and answers
2xxquickly. 410and402both show the user a way forward.- Your app alerts you before credits run out, using
GET /credits. - You have run the flow end to end with your own number.
| Endpoint | Purpose |
|---|---|
POST /start-verification | Start a session |
GET /check-verification-status | Read a session |
POST /user-identity | Link your own user ID |
GET /user-identity | Look up a linked ID |
GET /webhook-secret | Get your signing secret |
GET /credits | Read your balance |
GET /usage | Read 12 months of usage |
The full contract is in openapi.yaml. All bodies are JSON, and all timestamps are ISO 8601 in UTC.
Starts a session. Parameters go in the JSON body or the query string, and the query string wins.
| Parameter | Type | Description |
|---|---|---|
session_id | string | Your ID, using letters, digits, - and _. Generated if omitted. Must be unique: reusing one cancels its previous token. |
callback_url | string | Where the user goes after verifying. Defaults to the URL in your Settings. |
flow | string | phone (default), login, 2fa or age. |
provider | string | any (default), whatsapp or telegram. any lets the user pick. The other two lock the session to that channel. |
user_id | string | Required for flow=2fa. Our UUID or your linked ID. |
min_age | integer | Only for flow=age. |
reset | boolean | Only for flow=age. Runs the age check again. |
The sms block offers an SMS fallback for users without WhatsApp. Those sessions end with the status sms_validated.
Errors: 400 for invalid parameters or a missing key, 402 when credits run out, 404 for an unknown key or user_id, 503 when a provider isn't available.
{
"session": {
"session_id": "order-4821",
"validation_token": "xyz789",
"status": "pending",
"validity_timestamp": "2026-11-06T22:47:47.257Z",
"created_at": "2026-11-06T12:47:47.257Z",
"qr_code_scanned_at": null,
"previewed_at": null,
"opened_at": null,
"verified_at": null,
"success_link_clicked_at": null,
"whatsapp_message_sent_at": null,
"whatsapp_message_received_at": null,
"validated_phone_number": null
},
"links": {
"web": "https://your-app.example/verified?token=xyz789"
},
"whatsapp": {
"number": "18073600555",
"deeplink": "https://t.phone-verif.com/qr/xyz789",
"qr_code_url": "https://t.phone-verif.com/qr/xyz789",
"direct_link": "https://wa.me/18073600555?text=Verification%20token%3A%20%5Bxyz789%5D"
},
"sms": {
"number": "18073600555",
"qr_code_url": "sms:+18073600555?body=Verification%20token%3A%20%5Bxyz789%5D%20",
"direct_link": "sms:+18073600555?body=Verification%20token%3A%20%5Bxyz789%5D%20"
}
}Returns the same document as /start-verification, plus the fields of the session's flow. POST works too. You can only read sessions created with your own key.
| Parameter | Type | Description |
|---|---|---|
session_id | string | The session to read. Required without validation_token. |
validation_token | string | The token from the session or callback URL. |
reveal | boolean | Adds validated_phone_number on login and 2fa, for 1 credit per call. |
| Flow | Extra fields under session once verified |
|---|---|
phone | validated_phone_number, user_id |
login | user_id, is_new_user, and external_id if linked |
2fa | match |
age | age |
session.status moves forward through these values:
| Status | Meaning |
|---|---|
pending | Created, nothing has happened yet |
qr_code_scanned | The QR code or deeplink was opened |
whatsapp_previewed | WhatsApp fetched the link preview |
opened | The user opened the return link |
verified | Verified over WhatsApp or Telegram |
sms_validated | Verified over SMS |
Errors: 403 for a session that belongs to another key, 404 for an unknown session, 410 once it has expired.
curl "https://api.phone-verif.com/check-verification-status?session_id=order-4821" \
-H "x-api-key: $PHONE_VERIF_API_KEY"{
"session": {
"session_id": "order-4821",
"validation_token": "xyz789",
"status": "verified",
"verified_at": "2026-11-06T12:49:32.801Z",
"validated_phone_number": "33612345678",
"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10"
},
"links": {
"web": "https://your-app.example/verified?token=xyz789"
}
}Links your own user ID to our user_id, so you can pass yours to flow=2fa. It spends no credits. Both fields are required.
| Parameter | Type | Description |
|---|---|---|
user_id | string | Our UUID, from a verified session. |
external_id | string | Your ID for that user. |
curl -X POST https://api.phone-verif.com/user-identity \
-H "x-api-key: $PHONE_VERIF_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10", "external_id": "customer_42"}'{
"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10",
"external_id": "customer_42"
}Looks up a link from either side. Pass external_id or user_id in the query string. An unknown ID answers 404. It spends no credits.
curl "https://api.phone-verif.com/user-identity?external_id=customer_42" \
-H "x-api-key: $PHONE_VERIF_API_KEY"Returns the secret that signs your webhooks, and creates it on first use. See Verify webhook signatures.
curl https://api.phone-verif.com/webhook-secret \
-H "x-api-key: $PHONE_VERIF_API_KEY"{
"webhook_secret": "6f1d…"
}Returns your balance. It answers 200 even at zero, so you can poll it for alerts. Read credits.remaining and credits.exhausted. credits.key.allowed is null when the key has no limit of its own.
curl https://api.phone-verif.com/credits \
-H "x-api-key: $PHONE_VERIF_API_KEY"{
"top_up_url": "https://phone-verif.com/pricing",
"api_key": { "key_prefix": "abc123", "name": "Production" },
"credits": {
"remaining": 1250,
"exhausted": false,
"account": { "available": 1250 },
"key": { "used": 318, "allowed": null, "remaining": null, "uncapped": true }
}
}Returns the last 12 months, newest first. Empty months are included with zero counts. It spends no credits.
billing spells out the quantities that are billed: monthly active users for login, yearly active users for 2fa. active_users_by_flow is null for months recorded before per-flow tracking.
curl https://api.phone-verif.com/usage \
-H "x-api-key: $PHONE_VERIF_API_KEY"{
"months": [
{
"month": "2026-11",
"active_users": 42,
"active_users_by_flow": { "login": 28, "twofa": 15 },
"verifications": { "login": 28, "twofa": 15, "age": 0, "phone": 5 }
}
],
"years": [],
"billing": {
"login_monthly_active_users": [{ "month": "2026-11", "count": 28 }],
"twofa_yearly_active_users": [{ "year": "2026", "count": 15 }]
}
}We send a signed POST with Content-Type: application/json to the URL in your Settings.
| Event | When | Flow-specific fields |
|---|---|---|
verification_success | The message was matched to a session | phone: validated_phone_number, user_id. login: user_id, is_new_user, external_id. 2fa: match. age: age. |
age_verification_result | The age provider answered | age |
Every verification_success also has session_id, validation_token, status and the session timestamps. provider names the channel that completed the session, and is absent on a session locked to WhatsApp. When that channel is Telegram, flow=phone adds telegram.
{
"event": "verification_success",
"session_id": "order-4821",
"validation_token": "xyz789",
"status": "verified",
"created_at": "2026-11-06T12:47:47.257Z",
"qr_code_scanned_at": "2026-11-06T12:48:10.163Z",
"previewed_at": null,
"opened_at": null,
"verified_at": "2026-11-06T12:49:32.801Z",
"whatsapp_message_sent_at": "2026-11-06T12:49:33.102Z",
"whatsapp_message_received_at": "2026-11-06T12:49:32.640Z",
"validated_phone_number": "33612345678",
"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10"
}Errors use standard HTTP status codes and one JSON shape. Branch on the HTTP status, and show message only to developers. A 402 also carries developer_message, with the top-up link.
| Status | error | What to do |
|---|---|---|
400 | API_KEY_REQUIRED | Send the x-api-key header. |
400 | API_KEY_VALIDATION_ERROR | Check the key. Don't retry. |
400 | SESSION_ID_INVALID | Use only letters, digits, - and _. |
400 | SESSION_ID_OR_TOKEN_REQUIRED | Send session_id or validation_token. |
400 | INVALID_VALIDATION_TOKEN | Unknown token: start a new session. |
400 | INVALID_FLOW_PARAMETER | Fix flow, provider, user_id, min_age or reset. message names the problem. |
400 | PHONE_NUMBER_INVALID | reveal needs a verified login or 2fa session. |
402 | API_KEY_USAGE_LIMIT_EXCEEDED | Out of credits. Top up, then retry. |
403 | ACCESS_FORBIDDEN | This session belongs to another key. Don't retry. |
404 | API_KEY_NOT_FOUND | Unknown API key. Don't retry. |
404 | SESSION_NOT_FOUND | Unknown session. |
404 | USER_NOT_FOUND | Unknown user_id or external_id. |
410 | The session has expired. Start a new one and don't rely on error here. | |
500 | INTERNAL_SERVER_ERROR | Retry with backoff. |
502 | AGE_VERIFICATION_FAILED | The age provider failed. Retry with backoff. |
503 | AGE_VERIFICATION_UNAVAILABLE | Age verification isn't configured for your account. |
503 | TELEGRAM_UNAVAILABLE | Call again without provider. |
Retry only 5xx responses and network errors. Back off between attempts, and stop after a few tries. POST /start-verification is safe to retry with the same session_id: the latest call's token is the valid one.
{
"error": "API_KEY_USAGE_LIMIT_EXCEEDED",
"message": "The API key has reached its usage limit",
"code": 1004,
"http_code": 402,
"developer_message": "No credits left on this account. Top up at https://phone-verif.com/pricing to resume verifications."
}Send real requests from this page. Sign in and your key is filled in for you. Calls that complete a verification spend credits, unless you use your own registered number.