# 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.

> **For coding agents:** this file is the full guide. The machine-readable contract is [openapi.yaml](https://phone-verif.com/openapi.yaml) and the site index is [llms.txt](https://phone-verif.com/llms.txt). Keep the API key in a server-side secret named `PHONE_VERIF_API_KEY`. Read [Common mistakes](#common-mistakes) before writing code.

<!-- group: Get started -->

## Quickstart

<!-- anchor: quick-start -->

You need an API key. [Create an account](https://phone-verif.com/auth), finish [onboarding](https://phone-verif.com/onboarding) for 100 free credits, then copy a key from [API keys](https://phone-verif.com/api-keys).

The base URL is `https://api.phone-verif.com`.

### 1. Start a session

<!-- try: POST /start-verification -->

Call `POST /start-verification` from your server. Send a unique `session_id` and the `callback_url` the user returns to.

```bash tab=cURL title="Start a session"
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"
  }'
```

```javascript tab=Node title="Start a session"
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();
```

```python tab=Python title="Start a session"
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 tab=PHP title="Start a session"
<?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'];
```

```go tab=Go title="Start a session"
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)
```

### 2. Show the link

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`.

```json title="200 OK (shortened)"
{
  "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"
  }
}
```

### 3. Get the result

Add a webhook URL in [Settings](https://phone-verif.com/settings) and [verify its signature](#verify-webhook-signatures). We `POST` the result as soon as the message arrives.

```json title="Webhook body"
{
  "event": "verification_success",
  "session_id": "order-4821",
  "validation_token": "xyz789",
  "status": "verified",
  "validated_phone_number": "33612345678",
  "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10"
}
```

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](https://phone-verif.com/demo).

## How it works

<!-- flow-diagram -->

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.

1. Your server starts a session and receives a link containing a one-time token.
2. The user opens the link on their phone or scans it, then sends the pre-filled message.
3. WhatsApp delivers that message with the sender's number, which WhatsApp has already verified.
4. We match the token to your session and send you the result.
5. The user returns to your `callback_url` with `?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.

## Authentication

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.

```http title="Header"
x-api-key: YOUR_API_KEY
```

<!-- group: Guides -->

## Show the verification link

`whatsapp.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.

```jsx title="React"
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} />
  );
}
```

## Handle the result

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`.

```javascript title="Your callback route (Express)"
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');
});
```

## Verify webhook signatures

<!-- anchor: api-webhook-secret -->

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.

1. Fetch your secret once with `GET /webhook-secret` and store it as a server-side secret.
2. Read the raw request body before any JSON parsing. Parsing and re-serializing changes the bytes.
3. 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.

```javascript tab=Node title="Verify a webhook (Express)"
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
  });
```

```python tab=Python title="Verify a webhook (Flask)"
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 tab=PHP title="Verify a webhook"
<?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);
```

```go tab=Go title="Verify a webhook"
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)
}
```

## Login and 2FA

<!-- anchor: api-login-2fa -->

<!-- try: POST /start-verification flow=login -->

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](#age-verification) | 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](#post-user-identity). 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.

```json tab=login title="Webhook, flow=login"
{
  "event": "verification_success",
  "session_id": "order-4821",
  "status": "verified",
  "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10",
  "is_new_user": false
}
```

```json tab=2fa title="Webhook, flow=2fa"
{
  "event": "verification_success",
  "session_id": "order-4821",
  "status": "verified",
  "match": true
}
```

```bash title="Start a 2FA check"
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"}'
```

## Age verification

<!-- try: POST /start-verification flow=age -->

`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.

```bash title="Start an age check"
curl -X POST "https://api.phone-verif.com/start-verification?flow=age&min_age=18" \
  -H "x-api-key: $PHONE_VERIF_API_KEY"
```

```json title="Webhook, age_verification_result"
{
  "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"
  }
}
```

## Telegram

Every session is open to WhatsApp, SMS and our bot, [@PhoneVerif_com_bot](https://t.me/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_number` has the same format as on WhatsApp, so a number gets the same `user_id` on 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 `telegram` block, so check for it before showing it. `provider=telegram` answers `503` with `TELEGRAM_UNAVAILABLE`: fall back by calling again without `provider`.

```bash title="Lock a session to Telegram"
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"}'
```

```json title="Response block"
{
  "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"
  }
}
```

```json title="Webhook, flow=phone"
{
  "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"
  }
}
```

## Embed the hosted page

<!-- anchor: webview -->

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.

<!-- embed-demo -->

```html tab=iframe title="Embed"
<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>
```

```jsx tab=React title="Embed"
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"
    />
  );
}
```

```kotlin tab=Android title="Embed"
// 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"
)
```

```swift tab=iOS title="Embed"
// 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))
```

## Common mistakes

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. |

## Go-live checklist

- The API key is in a server-side secret, and appears in no client bundle.
- `callback_url` is 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 `2xx` quickly.
- `410` and `402` both 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.

<!-- group: API reference -->

## API overview

<!-- anchor: api -->

| Endpoint | Purpose |
|---|---|
| [`POST /start-verification`](#post-start-verification) | Start a session |
| [`GET /check-verification-status`](#get-check-verification-status) | Read a session |
| [`POST /user-identity`](#post-user-identity) | Link your own user ID |
| [`GET /user-identity`](#get-user-identity) | Look up a linked ID |
| [`GET /webhook-secret`](#get-webhook-secret) | Get your signing secret |
| [`GET /credits`](#get-credits) | Read your balance |
| [`GET /usage`](#get-usage) | Read 12 months of usage |

The full contract is in [openapi.yaml](https://phone-verif.com/openapi.yaml). All bodies are JSON, and all timestamps are ISO 8601 in UTC.

## POST /start-verification

<!-- anchor: api-start-verification -->

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.

```json title="200 OK"
{
  "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"
  }
}
```

## GET /check-verification-status

<!-- anchor: api-check-status -->

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.

```bash title="Request"
curl "https://api.phone-verif.com/check-verification-status?session_id=order-4821" \
  -H "x-api-key: $PHONE_VERIF_API_KEY"
```

```json title="200 OK, verified (shortened)"
{
  "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"
  }
}
```

## POST /user-identity

<!-- anchor: api-user-identity -->

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. |

```bash title="Request"
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"}'
```

```json title="200 OK"
{
  "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10",
  "external_id": "customer_42"
}
```

## GET /user-identity

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.

```bash title="Request"
curl "https://api.phone-verif.com/user-identity?external_id=customer_42" \
  -H "x-api-key: $PHONE_VERIF_API_KEY"
```

## GET /webhook-secret

Returns the secret that signs your webhooks, and creates it on first use. See [Verify webhook signatures](#verify-webhook-signatures).

```bash title="Request"
curl https://api.phone-verif.com/webhook-secret \
  -H "x-api-key: $PHONE_VERIF_API_KEY"
```

```json title="200 OK"
{
  "webhook_secret": "6f1d…"
}
```

## GET /credits

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.

```bash title="Request"
curl https://api.phone-verif.com/credits \
  -H "x-api-key: $PHONE_VERIF_API_KEY"
```

```json title="200 OK"
{
  "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 }
  }
}
```

## GET /usage

<!-- anchor: api-usage -->

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.

```bash title="Request"
curl https://api.phone-verif.com/usage \
  -H "x-api-key: $PHONE_VERIF_API_KEY"
```

```json title="200 OK (shortened)"
{
  "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 }]
  }
}
```

## Webhook events

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`.

```json title="verification_success, flow=phone"
{
  "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

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.

```json title="402 Payment Required"
{
  "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."
}
```

## Try the API

<!-- playground -->

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.
