Verification API Docs Download .md
v1.0 REST API

Verification API Reference

Detailed references, endpoints, and examples for integrating the WACM Verification Hub into your own applications.

Download as Markdown
Base URL
https://app.wacm.in/api/v1/verification

Authentication

All Verification API endpoints are authenticated using your Public API Key (vpub_...). Server-to-server requests can optionally include an HMAC-SHA256 signature for replay protection and payload integrity.

HTTP Header (Standard)

Pass your public key via X-Public-Key: vpub_... in every request.

Query Parameter (Fallback)

If your client cannot set HTTP headers, append ?public_key=vpub_... to the URL.

HMAC Signature (Optional Replay Protection)

For server-to-server security, supply X-Timestamp and X-Signature (computed as base64_encode(hash_hmac('sha256', timestamp . '.' . method . '.' . path . '.' . body, secret_key, true))). Timestamps older than 300s are rejected.

Authentication Headers 
X-Public-Key: vpub_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Optional HMAC Headers for Server-to-Server Security:
X-Timestamp: 1719123456
X-Signature: Nzk4NjhkYmJhNWQ...

Quick Start & Integration Flow

To implement verification into your frontend/backend stack:

1

Create a Profile

Create a Verification Profile in the WACM Dashboard to define channels, OTP lengths, and expiry times.

2

Request Verification

From your frontend, hit /request when a user enters their number. Store the returned request_id.

3

Validate OTP

Send the user's input to /verify. If successful, you'll receive a trust_key.

4

Consume Key

Your backend passes the trust_key to /status/{request_id} to definitively confirm identity before allowing the action.

Zero-Release Architecture

Mobile Configuration Discovery

GET /config

Allows mobile apps (iOS / Android / Flutter / React Native) to dynamically discover verification settings, OTP length, active WhatsApp bot numbers, and polling intervals at runtime. Prevents submitting new App Store / Play Store releases whenever you change your WhatsApp number, OTP rules, or verification profiles in the WACM dashboard.

Required Headers

Header Description
X-Public-Key Req Your API Key public token (vpub_...).
Response: Config 200 OK 
{
  "status": "active",
  "profile_id": "c1f7b8e2-...",
  "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": 60,
    "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

POST /request

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

Parameters

Parameter Description
identifier Mandatory Destination phone number (e.g. +1234567890 or 919876543210) or email address.
profile_id Optional UUID of Verification Profile. Optional when using API Key (auto-resolved from API key or company default).
channel Optional whatsapp or email. Defaults to whatsapp.
purpose Optional e.g., login, checkout. Defaults to default.
trust_key Optional Optional client/device trust token to bind with verification or skip re-verification.
ip_address Optional Used by Fraud Engine for rate limiting. Auto-captured if omitted.
user_agent Optional Used for device auditing. Auto-captured if omitted.
captcha_token Optional reCAPTCHA token. Required only if profile mandates captcha enforcement.
silent Optional If true, outbound OTP message will NOT be sent. Ideal for 1-Click WhatsApp verification. Defaults to false.
Response: Request 200 OK 
{
  "success": true,
  "request_id": "req_84jf9akd...",
  "otp_rules": {
    "length": 6,
    "type": "numeric",
    "expiry_seconds": 300,
    "resend_in_seconds": 60
  },
  "mobile_actions": {
    "one_click_whatsapp": {
      "enabled": true,
      "intent_url": "whatsapp://send?phone=15551234567&text=Verify%20Request%3A+req_84jf9akd...",
      "universal_url": "https://wa.me/15551234567?text=Verify%20Request%3A+req_84jf9akd..."
    },
    "polling_url": "/api/v1/verification/status/req_84jf9akd..."
  }
}

Validate Code

POST /verify

Validates an OTP submitted by the user.

Parameters

Parameter Description
request_id Mandatory The UUID returned from the /request step.
code Mandatory The OTP code entered by the user (1-20 characters, typically 4-8 digits).
Response: Verify (Success) 200 OK 
{
  "verified": true,
  "trust_key": "trust_abc123xyz..."
}
Response: Verify (Invalid Code) 200 OK 
{
  "verified": false
}

Resend Code

POST /resend

Resends a new OTP to the same identifier for an existing verification request. Useful when the user didn't receive the original code.

Tip (Recommended for Mobile Apps): Instead of storing `request_id` and managing expired states, your application can simply call POST /request again with the same identifier. If an unexpired request already exists, the server automatically reuses the same code, extends the expiration window, re-dispatches the message, and returns the same request_id with "reused": true. If the request expired, it seamlessly generates a fresh one.

Parameters

Parameter Description
request_id Mandatory The UUID returned from the /request step to resend.
Response: Resend 200 OK 
{
  "success": true,
  "message": "Resend initiated"
}
Zero-Release Architecture

WhatsApp One-Click Verification (Auto-Login)

Eliminate OTP typing friction entirely. Using the zero-release architecture, your app does not need to hardcode phone numbers or construct links manually. The API automatically returns ready-to-launch intent URLs that open the native WhatsApp application on iOS and Android.

1. Request Verification with Silent Flag

Call /request with silent: true so no outbound OTP message is sent. The response returns mobile_actions.one_click_whatsapp.

2. Launch WhatsApp Intent

On mobile apps (Swift / Kotlin / Flutter / React Native), open intent_url (whatsapp://send?phone=...). On web browsers, open universal_url (https://wa.me/...). WhatsApp opens directly with the pre-filled verification request.

3. Auto-Verify via Webhook & Polling

When the user taps "Send" in WhatsApp, the Verification Webhook intercepts the message and marks the request as verified. Your app polls polling_url; as soon as is_verified: true is returned, your app logs the user in immediately!

Mobile Actions Payload 
// Received in /request response:
{
  "mobile_actions": {
    "one_click_whatsapp": {
      "enabled": true,
      "intent_url": "whatsapp://send?phone=15551234567&text=Verify%20Request%3A+req_84jf9akd...",
      "universal_url": "https://wa.me/15551234567?text=Verify%20Request%3A+req_84jf9akd..."
    },
    "polling_url": "/api/v1/verification/status/req_84jf9akd..."
  }
}

Check Status & Consume Trust Key

GET /status/{request_id}

Retrieves the real-time status of a verification request. Used by frontends polling during 1-Click WhatsApp flows, or by your backend server to independently verify that the trust_key provided by the client is authentic and valid.

Path Parameters

Parameter Description
request_id Mandatory The UUID of the verification request session to inspect.

Statuses

verified Verification completed. Includes is_verified: true and trust_key.
pending Awaiting OTP validation or WhatsApp message. is_verified: false.
expired OTP expired before completion.
Response: Status (Verified) 200 OK 
{
  "status": "verified",
  "is_verified": true,
  "trust_key": "trust_abc123xyz...",
  "identifier": "+1234567890",
  "channel": "whatsapp",
  "verified_at": "2026-06-22T19:35:00+00:00"
}
Response: Status (Pending) 200 OK 
{
  "status": "pending",
  "is_verified": false
}

© 2026 WACM. All rights reserved. API Version 1.0.