Verification API Reference

Overview

The Verification API provides multi-channel identity verification (WhatsApp and Email) with fraud prevention, rate limiting, and a server-driven Zero-Release mobile architecture.

Authentication

All Verification API endpoints authenticate via your Public API Key (vpub_...). For server-to-server payload verification and a timestamp window, requests can include an HMAC-SHA256 signature and timestamp.

Headers

HMAC Signature Calculation

Construct a payload string of timestamp.method.path.body and sign it on your backend with your API secret key. Use the uppercase HTTP method, the path without its leading slash or query string, and the exact serialized body sent:

const crypto = require('crypto');

function computeSignature(timestamp, method, path, body, secretKey) {
    const payload = `${timestamp}.${method}.${path}.${body}`;
    return crypto
        .createHmac('sha256', secretKey)
        .update(payload)
        .digest('base64');
}

// Serialize once and send these exact bytes as the HTTP request body.
const requestBody = JSON.stringify({ identifier: '+919876543210', channel: 'whatsapp' });
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = computeSignature(timestamp, 'POST', 'api/v1/verification/request', requestBody, secretKey);

$timestamp = time();
$method = 'POST';
$path = 'api/v1/verification/request';
$body = json_encode(['identifier' => '+919876543210', 'channel' => 'whatsapp']);
$payload = $timestamp . '.' . $method . '.' . $path . '.' . $body;
$signature = base64_encode(hash_hmac('sha256', $payload, $secretKey, true));

Quick Start & Integration Flow

Mobile Configuration Discovery

Allows mobile applications (iOS, Android, Flutter, React Native) and web clients to dynamically discover verification profile settings, OTP length, active WhatsApp bot numbers, and recommended polling intervals at runtime. Prevents submitting new App Store / Play Store app updates when backend settings change.

Mandatory Headers

No query or request body parameters required.

curl -X GET https://app.wacm.in/api/v1/verification/config \
     -H "X-Public-Key: vpub_your_public_key"

Response (200 OK)

{
  "status": "active",
  "profile_id": "c1f7b8e2-8924-4f0e-b7d6-e24c519f3901",
  "profile_name": "Default Verification Profile",
  "channels": ["whatsapp", "email"],
  "default_channel": "whatsapp",
  "otp": {
    "length": 6,
    "type": "numeric",
    "expiry_minutes": 5,
    "expiry_seconds": 300,
    "resend_cooldown_seconds": 30,
    "max_attempts": 3
  },
  "whatsapp": {
    "enabled": true,
    "one_click_enabled": true,
    "bot_phone": "15551234567"
  },
  "polling": {
    "status_url_template": "/api/v1/verification/status/{request_id}",
    "recommended_interval_ms": 2000,
    "timeout_seconds": 120
  }
}

Request Verification

Initiates a verification request and dispatches an OTP or generates 1-Click WhatsApp intent URLs.

Mandatory Parameters

Optional Parameters

curl -X POST https://app.wacm.in/api/v1/verification/request \
     -H "X-Public-Key: vpub_your_public_key" \
     -H "Content-Type: application/json" \
     -d '{
       "identifier": "+1234567890",
       "channel": "whatsapp",
       "purpose": "login"
     }'

Response (Standard New Request)

{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "profile_id": "c1f7b8e2-8924-4f0e-b7d6-e24c519f3901",
  "otp_rules": {
    "length": 6,
    "type": "numeric",
    "expiry_seconds": 300,
    "resend_in_seconds": 30
  },
  "mobile_actions": {
    "one_click_whatsapp": {
      "enabled": true,
      "intent_url": "whatsapp://send?phone=15551234567&text=Verify%20Request%3A+550e8400-e29b-41d4-a716-446655440000",
      "universal_url": "https://wa.me/15551234567?text=Verify%20Request%3A+550e8400-e29b-41d4-a716-446655440000"
    },
    "polling_url": "/api/v1/verification/status/550e8400-e29b-41d4-a716-446655440000"
  }
}

Response (Cached / Skip Verification)

If the user has verified recently within your profile's trust caching window, the request immediately succeeds without issuing a new request ID or trust key. Polling and intent URLs are null; cached/reused flags may be omitted in other response branches:

{
  "success": true,
  "cached": true,
  "verified": true,
  "profile_id": "c1f7b8e2-8924-4f0e-b7d6-e24c519f3901",
  "otp_rules": { "length": 6, "type": "numeric", "expiry_seconds": 300, "resend_in_seconds": 30 },
  "mobile_actions": { "one_click_whatsapp": { "enabled": true, "intent_url": null, "universal_url": null }, "polling_url": null }
}

Response (Reused / Session Resend)

When re-requesting verification for the same identifier while a session is still active, the server automatically reuses the existing code, extends the expiration window, increments the resends count, and returns "reused": true:

{
  "success": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "reused": true,
  "profile_id": "c1f7b8e2-8924-4f0e-b7d6-e24c519f3901",
  "otp_rules": {
    "length": 6,
    "type": "numeric",
    "expiry_seconds": 300,
    "resend_in_seconds": 30
  },
  "mobile_actions": {
    "one_click_whatsapp": {
      "enabled": true,
      "intent_url": "whatsapp://send?phone=15551234567&text=Verify%20Request%3A+550e8400-e29b-41d4-a716-446655440000",
      "universal_url": "https://wa.me/15551234567?text=Verify%20Request%3A+550e8400-e29b-41d4-a716-446655440000"
    },
    "polling_url": "/api/v1/verification/status/550e8400-e29b-41d4-a716-446655440000"
  }
}

WhatsApp 1-Click Verification (Auto-Login)

Eliminate manual OTP typing entirely. Using the server-driven response, your mobile app launches the native WhatsApp app pre-filled with the verification message.

Validate Code

Validates an OTP submitted manually by the user in your frontend.

Mandatory Parameters

No optional parameters accepted.

curl -X POST https://app.wacm.in/api/v1/verification/verify \
     -H "X-Public-Key: vpub_your_public_key" \
     -H "Content-Type: application/json" \
     -d '{
       "request_id": "550e8400-e29b-41d4-a716-446655440000",
       "code": "123456"
     }'

Responses

{
  "verified": true,
  "trust_key": "trust_abc123xyz789..."
}

{
  "verified": false
}

{
  "error": "Maximum verification attempts reached. Try again in 30 minute(s)."
}

Check Status & Retrieve Trust Key

Retrieves the current status of a verification request. Used by frontends polling during 1-Click WhatsApp flows, or by your backend server to retrieve the verified session details. This endpoint does not consume the trust key or create an application login session; the integrating backend is responsible for its authentication flow. The returned trust key is the caller-supplied value and may be null; it is not a newly issued login token.

Mandatory Path Parameters

No optional parameters accepted.

curl -X GET https://app.wacm.in/api/v1/verification/status/550e8400-e29b-41d4-a716-446655440000 \
     -H "X-Public-Key: vpub_your_public_key"

Response (Verified)

{
  "status": "verified",
  "is_verified": true,
  "trust_key": "trust_abc123xyz789...",
  "identifier": "+1234567890",
  "channel": "whatsapp",
  "verified_at": "2026-06-23T10:30:00+00:00"
}

Response (Pending)

{
  "status": "pending",
  "is_verified": false
}

Possible Status Values

• verified: Verification completed successfully (contains is_verified: true and trust_key).
• pending: Awaiting OTP validation or 1-Click WhatsApp message (is_verified: false).
• expired: OTP or session expired before completion.
• failed: Maximum incorrect attempts reached.
• blocked: Blocked by fraud prevention rules.

Resend Code

Resends an OTP to the same identifier for an existing, pending verification request.

Mandatory Parameters

No optional parameters accepted.

curl -X POST https://app.wacm.in/api/v1/verification/resend \
     -H "X-Public-Key: vpub_your_public_key" \
     -H "Content-Type: application/json" \
     -d '{
       "request_id": "550e8400-e29b-41d4-a716-446655440000"
     }'

Response

{
  "success": true,
  "message": "Resend initiated"
}

Magic Link Verification (Browser)

For email verification flows, users receive a clickable magic link. When the user clicks the link in their browser or email client, this public endpoint verifies the token and renders a browser confirmation page.

Mandatory Path Parameters

Public browser endpoint; no API key headers or optional parameters required.

Webhook Integration

Instead of continuous polling, you can configure webhooks in your Verification Profile to receive real-time notifications when verification events occur.

Supported Events

• verification.requested — Dispatched when a new verification request is created
• verification.successful — Dispatched as soon as an OTP, 1-Click WhatsApp, or Magic Link is verified
• verification.failed — Dispatched when attempts exceed limits or fraud prevention is triggered

Webhook Payload Example

{
  "event": "verification.successful",
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "identifier": "+1234567890",
    "channel": "whatsapp",
    "purpose": "login",
    "trust_key": "trust_abc123xyz789..."
  },
  "timestamp": "2026-06-23T10:30:00Z"
}

Fraud Prevention & Security Features

The Verification Hub includes enterprise-grade fraud mitigation mechanisms:

• OTP Bombing Protection: Cooldown windows and per-identifier request throttling prevent abuse.
• IP Velocity Limiting: Enforces caps on unique phone numbers and emails initiated per IP within time windows.
• Disposable Email Filter: Blocks 10-minute and disposable email domains in real-time.
• reCAPTCHA Integration: Optional enforcement (disabled, always, or risk-based after failed attempts).
• IP & Country Allow/Blocklists: Restrict verification traffic to authorized regional markets.

Rate Limits

Data Model

VerificationProfile

Central entity configuring verification behavior, channels, OTP rules, security thresholds, and webhooks.

VerificationApiKey

API key pairs for authenticating client applications and backend systems.

VerificationRequest

Tracks individual verification sessions and audit trails.

Error Responses

{
  "error": "Validation failed",
  "details": {
    "identifier": ["The identifier field is required."],
    "channel": ["The selected channel is invalid."]
  }
}

{
  "error": "Too many verification attempts. Please try again in 30 minute(s)."
}

Flowmaker Integration

The Verification API integrates seamlessly with the WACM AI Flow Builder through dedicated flow nodes:

• Request Verification Node: Dispatches verification within automated customer journeys
• Verify Code Node: Validates user input received in conversational flows
• Check Status Node: Conditions subsequent branch logic based on verified trust status

Related Documentation

• WhatsApp Business API — Direct WhatsApp messaging and template dispatches
• AI Flow Builder — Build visual conversational journeys with built-in verification
• eCommerce Storefront API — Verify customer identities at checkout