Developer Reference

MebbOTP REST API Documentation

Welcome to the MebbOTP Developer API. Our high-throughput REST API allows you to programmatically provision real non-VoIP phone numbers, fetch instant SMS OTP verification codes, automate multi-country verifications, and listen for instant real-time webhook callbacks.

Production Base URL

https://mebbotp.com/api/v1

Authentication

All authenticated API requests require your unique secret API key. You can pass your key via HTTP headers or request parameters:

Standard Bearer Header (Recommended)

Authorization: Bearer YOUR_API_KEY

Alternative Custom Header

X-API-Key: YOUR_API_KEY

Rate Limits & HTTP Status Codes

Default rate limit is 60 requests per minute. If exceeded, the API returns HTTP 429 Too Many Requests with a Retry-After: 60 header.

Code	Error Code	Description
200 / 201	SUCCESS	Request processed successfully.
400	BAD_REQUEST	Missing or invalid parameters.
401	UNAUTHORIZED	Missing or invalid secret API key.
402	INSUFFICIENT_BALANCE	Wallet balance is lower than order price.
403	FORBIDDEN	API access restricted, banned, or IP not whitelisted.
404	NOT_FOUND	Requested order or endpoint does not exist.
429	RATE_LIMIT_EXCEEDED	Too many requests per minute.
503	STOCK_UNAVAILABLE	Provider lines currently busy or stock depleted.

GET

/user/balance

Retrieve your current wallet balance in both USD ($) and NGN (₦), active orders count, and account settings.

200 OK Response

{
  "status": "success",
  "status_code": 200,
  "message": "Account balance retrieved successfully.",
  "data": {
    "user_uid": "USR-849204",
    "username": "developer_pro",
    "balance_usd": 24.50,
    "balance_ngn": 37975.00,
    "exchange_rate_ngn": 1550.00,
    "active_orders_count": 1,
    "webhook_url": "https://yourdomain.com/webhooks/otp",
    "api_status": "active",
    "rate_limit_per_min": 60
  }
}

GET

/services

Fetch list of supported services, real-time pricing in USD & NGN, and stock numbers.

Query Parameters:

• country (string, optional, default: "us") — 2-letter ISO code (e.g. "us", "gb", "ng").

• line_type (string, optional) — "usa_standard", "usa_v2", "global_standard", "global_v2".

POST

/order/create

Purchase and allocate an instant dedicated phone number for OTP verification.

Request JSON Payload

{
  "service": "whatsapp",
  "country": "us",
  "line_type": "usa_standard",
  "max_price": 1.50
}

201 Created Response

{
  "status": "success",
  "status_code": 201,
  "message": "Phone number allocated successfully. Send your verification code now.",
  "data": {
    "order_id": "ORD-7492019482",
    "phone_number": "+12025550143",
    "service": "WhatsApp",
    "country": "us",
    "line_type": "usa_standard",
    "cost_usd": 0.75,
    "cost_ngn": 1162.50,
    "status": "PENDING",
    "otp_code": null,
    "expires_in": 1200,
    "expires_at": "2026-08-27 18:30:00"
  }
}

GET

/order/status?order_id=ORD-XXXX

Poll live OTP code reception status for an active order.

200 OK (When OTP Arrives)

{
  "status": "success",
  "status_code": 200,
  "data": {
    "order_id": "ORD-7492019482",
    "phone_number": "+12025550143",
    "service": "WhatsApp",
    "status": "COMPLETED",
    "otp_status": "RECEIVED",
    "otp_code": "849201",
    "full_sms": "Your WhatsApp verification code is 849-201. Do not share this code.",
    "expires_at": "2026-08-27 18:30:00"
  }
}

POST

/order/cancel

Cancel an unreceived order and receive an immediate full refund back into your wallet balance.

Request JSON Payload

{
  "order_id": "ORD-7492019482"
}

Real-Time Webhooks

Instead of polling, configure your webhook URL to receive instant HTTP POST alerts the moment an SMS code arrives on any active number.

Verifying Webhook Signatures (HMAC-SHA256)

Every webhook request includes a X-Mebb-Signature header generated using HMAC-SHA256 with your Secret API Key:

// PHP Verification Example
$signature = $_SERVER['HTTP_X_MEBB_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');
$expectedSignature = hash_hmac('sha256', $payload, $YOUR_SECRET_API_KEY);

if (hash_equals($expectedSignature, $signature)) {
    // Verified authentic payload from MebbOTP
    $event = json_decode($payload, true);
}