v1.0OpenAPI 3.2.0SMS-Activate Compatible

Download OpenAPI Document Get Your API Key

API protocol for working with SMS Reception (SMS-Activate Compatible)

Automate OTP SMS verification, FlashCall and Email OTP rentals via REST API into Telegram bots, scripts, tools, and websites.

Software Connection Guide

Choose any software that includes SMS-Activate among its SMS reception services.

Select SMS-Activate as the service for receiving SMS.

Replace the host from https://api.sms-activate.ae to https://hero-sms.com/stubs/handler_api.php in your software settings.

https://hero-sms.com/stubs/handler_api.php

Enter the API key from your account profile (request it on our website).

If you face any difficulties, contact our tech support, please. We will deal with everything.

API Server

https://hero-sms.com/api

Authentication

x-api-key: your_api_key_here

#!/usr/bin/env bash
# OTP Activation Flow (SMS-Activate Compatible)
set -euo pipefail

BASE_URL="https://hero-sms.com/stubs/handler_api.php"
API_KEY="YOUR_API_KEY"
SERVICE="tg"   # Telegram service code
COUNTRY="0"    # Country ID (e.g. 0 = Russia, 10 = Vietnam)

echo "==> 1. Checking account balance..."
curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=getBalance"
echo ""

echo "==> 2. Ordering a phone number..."
BUY_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=getNumber&service=${SERVICE}&country=${COUNTRY}")
echo "Response: ${BUY_RES}"

# Expected format: ACCESS_NUMBER:$ACTIVATION_ID:$PHONE
if [[ "${BUY_RES}" != ACCESS_NUMBER* ]]; then
  echo "Error buying number: ${BUY_RES}"
  exit 1
fi

ACTIVATION_ID=$(echo "${BUY_RES}" | cut -d':' -f2)
PHONE_NUMBER=$(echo "${BUY_RES}" | cut -d':' -f3)
echo "Acquired number: +${PHONE_NUMBER} (Activation ID: ${ACTIVATION_ID})"

echo "==> 3. Polling for OTP code..."
MAX_ATTEMPTS=24 # 2 minutes (24 * 5 seconds)
OTP_CODE=""

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
  sleep 5
  STATUS_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=getStatus&id=${ACTIVATION_ID}")
  echo "Poll ${i}/${MAX_ATTEMPTS}: ${STATUS_RES}"

  if [[ "${STATUS_RES}" == STATUS_OK* ]]; then
    OTP_CODE=$(echo "${STATUS_RES}" | cut -d':' -f2)
    echo "Successfully received OTP: ${OTP_CODE}"
    break
  fi

  if [[ "${STATUS_RES}" == "STATUS_CANCEL" ]]; then
    echo "Activation was cancelled."
    exit 1
  fi
done

if [[ -n "${OTP_CODE}" ]]; then
  echo "==> 4. Finishing activation..."
  FINISH_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=setStatus&id=${ACTIVATION_ID}&status=6")
  echo "Finish status: ${FINISH_RES}"
else
  echo "==> Timed out waiting for SMS. Requesting cancel/refund..."
  CANCEL_RES=$(curl -s -H "x-api-key: ${API_KEY}" "${BASE_URL}?action=setStatus&id=${ACTIVATION_ID}&status=8")
  echo "Cancel status: ${CANCEL_RES}"
fi

Cursor / Windsurf / Claude Code / Copilot

Cursor / Windsurf / Claude Code Integration Prompt

Download openapi.json

Zero-friction AI prompt for one-shot integration with Cursor, Windsurf, Claude Code, and ChatGPT.

Integration Prompt Excerpt

# OTP & SMS Gateway Integration Guide (SMS-Activate Compatible)

You are tasked with building a robust, production-grade integration with this SMS/OTP Verification Service.
This service is fully compatible with the standard **SMS-Activate** protocol and also exposes a standard REST API.

---

## 1. OpenAPI Specification Import
Before writing code, import or inspect the full OpenAPI specification at:
```
https://hero-sms.com/api/docs/openapi?download=1
```
Use this JSON specification in Cursor, Windsurf, Postman, or Claude to inspect all schemas, models, and endpoints.

---

## 2. Base Endpoint & Protocol Overview
- **Primary SMS-Activate Endpoint**: `https://hero-sms.com/stubs/handler_api.php`
- **Supported HTTP Methods**: `GET` (parameters via query string) and `POST` (supports JSON, multipart, or application/x-www-form-urlencoded).
- **Authentication**:
  - Query parameter: `?api_key=YOUR_API_KEY`
  - Or HTTP Header: `x-api-key: YOUR_API_KEY`
  - Or Authorization header: `Authorization: Bearer YOUR_API_KEY`

---

## 3. Complete Activation Lifecycle Steps

### Step 1: Check Account Balance (`getBalance`)
Query available USD balance before placing orders.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getBalance`
- **Success Response**:
  `ACCESS_BALANCE:15.50`
- **Error Responses**:
  `BAD_KEY` (invalid API key)

### Step 2: Rent / Buy Phone Number (`getNumber` or `getNumberV2`)
Request a temporary phone number for a target service and country.
- **Request (Plain Text)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getNumber&service=tg&country=0`
- **Success Response**:
  `ACCESS_NUMBER:123456:84987654321`
  - Format: `ACCESS_NUMBER:<activationId>:<phoneNumber>`
- **Request (JSON Format - V2)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getNumberV2&service=tg&country=0`
- **Success Response (V2 JSON)**:
  ```json
  {
    "activationId": "123456",
    "phoneNumber": "84987654321",
    "activationCost": 0.15,
    "currency": "USD"
  }
  ```
- **Common Error Responses**:
  - `NO_NUMBERS`: No numbers currently in stock for this service/country.
  - `NO_BALANCE`: Insufficient balance.
  - `BAD_SERVICE`: Invalid service or country parameter.

### Step 3: Poll for OTP Code (`getStatus` or `getStatusV2`)
Poll every 3–5 seconds until the SMS verification code is received.
- **Request (Plain Text)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getStatus&id=123456`
- **Responses**:
  - `STATUS_WAIT_CODE`: Still waiting for SMS. Continue polling.
  - `STATUS_OK:987654`: OTP received! Code is `987654`.
  - `STATUS_CANCEL`: Activation was cancelled or refunded. Stop polling.
- **Request (JSON Format - V2)**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getStatusV2&id=123456`
- **Success Response (V2 JSON)**:
  ```json
  {
    "status": "OK",
    "smsCode": "987654",
    "smsText": "Your verification code is 987654",
    "receivedAt": "2026-10-07T10:00:00.000Z"
  }
  ```

### Step 4: Finish Activation (`setStatus=6`)
Call after receiving the OTP code and successfully verifying the user/service account.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=setStatus&id=123456&status=6`
- **Success Response**:
  `ACCESS_ACTIVATION`

### Step 5: Cancel & Refund Activation (`setStatus=8`)
Call if timed out or if no SMS was received and you wish to release the number and refund wallet.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=setStatus&id=123456&status=8`
- **Success Response**:
  `ACCESS_CANCEL`
- **Error**:
  `EARLY_CANCEL_DENIED` (cannot cancel within early cooldown period, wait a minute and retry).

### Step 6: Query Prices & Stock (`getPrices`)
Retrieve available stock count and pricing for a service and country.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getPrices&service=tg&country=0`
- **Success Response (JSON)**:
  ```json
  {
    "0": {
      "tg": {
        "cost": 0.15,
        "count": 420
      }
    }
  }
  ```

### Step 7: Query Countries List (`getCountries`)
List all supported country IDs and localized names.
- **Request**:
  `GET https://hero-sms.com/stubs/handler_api.php?action=getCountries`
- **Success Response (JSON Array)**:
  ```json
  [
    { "id": 0, "rus": "Россия", "eng": "Russia", "chn": "俄罗斯" },
    { "id": 10, "rus": "Вьетнам", "eng": "Vietnam", "chn": "越南" }
  ]
  ```

---

## 4. Coding Assistant Implementation Requirements
When implementing the client module for your project:
1. **Class-based architecture**: Create an `OtpClient` with methods: `getBalance()`, `rentNumber(service, country)`, `pollOtp(activationId, options)`, `finish(activationId)`, `cancel(activationId)`, `getPrices(service, country)`, and `getCountries()`.
2. **Polling logic**:
   - Interval: 3 to 5 seconds.
   - Timeout: 120 seconds default.
   - If timeout is reached, automatically call `setStatus=8` to refund the balance.
3. **Robust error handling**:
   - Parse plain text prefixes: `ACCESS_NUMBER:<id>:<phone>`, `STATUS_OK:<code>`, and `ACCESS_BALANCE:<amount>`.
   - Throw explicit typed errors on `NO_NUMBERS`, `NO_BALANCE`, and `BAD_KEY`.
4. **Environment variable configuration**: Read `OTP_API_KEY` and optional `OTP_API_BASE_URL` (defaults to `https://hero-sms.com/stubs/handler_api.php`).

Common API

3 endpoints

GET/api/user/balance

Common API

Check Wallet Balance & Account Info

Query available wallet balance (VND & USD) and linked account email.

Headers

x-api-key

your_api_key_here

Your account API Key

Example Response

{
  "success": true,
  "email": "[email protected]",
  "balance": 250000,
  "balanceVnd": 250000,
  "balanceUsd": 9.47,
  "balanceUsdFormatted": "$9.47",
  "usdRate": 26400
}

GET/api/otp/loyalty

Common API

VIP Loyalty Tier & Discount Rates

Check current VIP tier, active discount rate applied to rentals, last 7 days deposit/spending, and requirements for next tier.

Headers

x-api-key

your_api_key_here

Your account API Key

Example Response

{
  "success": true,
  "data": {
    "userStatus": {
      "userId": "user_2tX8849...",
      "currentTier": 2,
      "tierName": "VIP 2",
      "discountPercent": 5,
      "weeklySpending": 350000,
      "nextTierSpendingNeeded": 150000,
      "nextTier": 3
    },
    "tiers": [
      {
        "tier": 0,
        "name": "Thành viên",
        "minWeekly": 0,
        "discountPercent": 0
      },
      {
        "tier": 1,
        "name": "VIP 1",
        "minWeekly": 100000,
        "discountPercent": 3
      },
      {
        "tier": 2,
        "name": "VIP 2",
        "minWeekly": 300000,
        "discountPercent": 5
      },
      {
        "tier": 3,
        "name": "VIP 3",
        "minWeekly": 500000,
        "discountPercent": 8
      },
      {
        "tier": 4,
        "name": "VIP 4",
        "minWeekly": 1000000,
        "discountPercent": 12
      },
      {
        "tier": 5,
        "name": "VIP 5",
        "minWeekly": 2000000,
        "discountPercent": 15
      }
    ]
  }
}

GET/api/otp/tiers

Common API

VIP Loyalty Tiers & Discount Table (Public)

Query complete list of VIP tiers and their corresponding discount percentages. No API key required.

Example Response

{
  "success": true,
  "data": {
    "tiers": [
      {
        "tier": 0,
        "name": "Thành viên",
        "minWeekly": 0,
        "discountPercent": 0
      },
      {
        "tier": 1,
        "name": "VIP 1",
        "minWeekly": 100000,
        "discountPercent": 3
      },
      {
        "tier": 2,
        "name": "VIP 2",
        "minWeekly": 300000,
        "discountPercent": 5
      },
      {
        "tier": 3,
        "name": "VIP 3",
        "minWeekly": 500000,
        "discountPercent": 8
      },
      {
        "tier": 4,
        "name": "VIP 4",
        "minWeekly": 1000000,
        "discountPercent": 12
      },
      {
        "tier": 5,
        "name": "VIP 5",
        "minWeekly": 2000000,
        "discountPercent": 15
      }
    ],
    "description": "Weekly deposit tier discount table. Tiers are evaluated based on 7-day deposit total."
  }
}

Number rental & code API

18 endpoints

GET/api/otp/countries

Number rental & code API

List of Supported Countries

Get all available countries with country ID, flag, and phone prefix.

Example Response

{
  "success": true,
  "data": [
    {
      "id": 10,
      "name": "Vietnam",
      "code": "vn",
      "prefix": "+84"
    },
    {
      "id": 1,
      "name": "United States",
      "code": "us",
      "prefix": "+1"
    },
    {
      "id": 6,
      "name": "Indonesia",
      "code": "id",
      "prefix": "+62"
    },
    {
      "id": 4,
      "name": "Philippines",
      "code": "ph",
      "prefix": "+63"
    },
    {
      "id": 0,
      "name": "Russia",
      "code": "ru",
      "prefix": "+7"
    }
  ]
}

GET/api/otp/services

Number rental & code API

List of SMS Services & Apps

Get list of apps supporting OTP verification (Telegram, Google, TikTok, Facebook, WhatsApp...) with available counts and base prices.

Parameters

Field	Type	Required	Description
country	number \| string	Optional	Filter by country ID (e.g. 10 for Vietnam, 1 for USA, 6 for Indonesia)

Example Response

{
  "success": true,
  "tier": 0,
  "data": [
    {
      "code": "tg",
      "name": "Telegram",
      "count": 350000,
      "icon": "/icons/services/tg.webp",
      "prices": {
        "sellingUsd": 0.15,
        "sellingVnd": 4000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "code": "go",
      "name": "Google, YouTube, Gmail",
      "count": 500000,
      "icon": "/icons/services/go.webp",
      "prices": {
        "sellingUsd": 0.05,
        "sellingVnd": 1400,
        "tier": 0,
        "discountPercent": 0
      }
    }
  ]
}

GET/api/otp/prices

Number rental & code API

Detailed Pricing & Offers Orderbook

Look up detailed pricing for a service in a specific country, including orderbook offers for both SMS and FlashCall.

Parameters

Field	Type	Required	Description
service	string	Required	Service code (e.g. tg, go, fb, wa, lf, dr...)
country	number \| string	Optional	Country ID (e.g. 10, 1, 6...)
verificationType	string	Optional	'sms' (default) or 'call' (FlashCall)

Example Response

{
  "success": true,
  "tier": 0,
  "data": [
    {
      "service": "tg",
      "country": "10",
      "count": 12500,
      "prices": {
        "sellingUsd": 0.15,
        "sellingVnd": 4000,
        "tier": 0,
        "discountPercent": 0
      },
      "offers": [
        {
          "sellingUsd": 0.15,
          "sellingVnd": 4000,
          "count": 500
        },
        {
          "sellingUsd": 0.18,
          "sellingVnd": 4800,
          "count": 2000
        }
      ]
    }
  ]
}

GET/api/otp/operators

Number rental & code API

List Supported Telco Operators

Get list of telco operators available for a specific country and service.

Parameters

Field	Type	Required	Description
country	number \| string	Optional	Country ID (e.g. 10 for Vietnam)
service	string	Optional	Service code (e.g. tg, go, fb...)

Example Response

{
  "success": true,
  "data": [
    {
      "code": "any",
      "name": "Bất kỳ nhà mạng nào (Nhanh nhất)"
    },
    {
      "code": "viettel",
      "name": "Viettel"
    },
    {
      "code": "mobifone",
      "name": "Mobifone"
    },
    {
      "code": "vinaphone",
      "name": "Vinaphone"
    }
  ]
}

POST/api/otp/buy

Number rental & code API

Rent Short-Term Number for OTP (SMS / FlashCall)

Create short-term rental order (~20 min). Supports operator selection, price ceiling, and batch ordering. Returns system orderCode.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Parameters

Field	Type	Required	Description
service	string	Required	Service code (e.g. tg, go, fb, wa, lf...)
country	number \| string	Required	Country ID (e.g. 10 for Vietnam, 1 for USA)
verificationType	string	Optional	'sms' (default) or 'call' (FlashCall)
operator	string	Optional	Target telco operator (e.g. 'viettel', 'mobifone', or 'any' - default)
maxPrice	number	Optional	Maximum price ceiling (VND) you are willing to pay
amount	number	Optional	Batch purchase quantity (1 to 10, default: 1)

Request Body (JSON)

{
  "service": "tg",
  "country": 10,
  "verificationType": "sms",
  "operator": "any",
  "maxPrice": 5000,
  "amount": 1
}

Example Response

{
  "success": true,
  "tier": 0,
  "balanceAfter": 246000,
  "data": [
    {
      "id": "ACT8K3N9",
      "orderCode": "ACT8K3N9",
      "phone": "84931002233",
      "service": "tg",
      "country": "10",
      "status": "WAIT_CODE",
      "price": {
        "sellingUsd": 0.15,
        "sellingVnd": 4000,
        "tier": 0,
        "discountPercent": 0
      },
      "createdAt": "2026-10-06T08:00:00.000Z",
      "expiredAt": "2026-10-06T08:20:00.000Z"
    }
  ]
}

GET/api/otp/activations

Number rental & code API

List Active Rentals & History

Get list of active rentals waiting for OTP or your complete rental history.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
status	string	Optional	'ACTIVE' (waiting for OTP) or 'FINISHED', 'CANCELLED', 'REFUNDED'
limit	number	Optional	Limit per page (default: 20)

Example Response

{
  "success": true,
  "data": [
    {
      "id": "ACT8K3N9",
      "orderCode": "ACT8K3N9",
      "phone": "84931002233",
      "service": "tg",
      "serviceName": "Telegram",
      "country": "10",
      "status": "WAIT_CODE",
      "otpCode": null,
      "createdAt": "2026-10-06T08:00:00.000Z"
    }
  ]
}

GET/api/otp/activations/{id}

Number rental & code API

Check Order Status & Get OTP Code

Query order status using system orderCode (e.g. ACT8K3N9). When SMS or call arrives, the OTP code is returned instantly.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System internal orderCode (e.g. ACT8K3N9)

Example Response

{
  "success": true,
  "data": {
    "id": "ACT8K3N9",
    "orderCode": "ACT8K3N9",
    "status": "OK",
    "phone": "84931002233",
    "lastOtp": {
      "code": "891024",
      "text": "Telegram code: 891024"
    },
    "otpList": [
      {
        "code": "891024",
        "text": "Telegram code: 891024",
        "receivedAt": "2026-10-06T08:02:15.000Z"
      }
    ]
  }
}

POST/api/otp/activations/{id}/retry

Number rental & code API

Request Additional / Next OTP Code

Set status back to waiting for additional SMS codes during active rental time.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode

Example Response

{
  "success": true,
  "status": "WAIT_CODE",
  "message": "Đã sẵn sàng nhận mã tiếp theo."
}

POST/api/otp/activations/{id}/replace

Number rental & code API

Replace with New Phone Number

Replace with a new phone number free of charge if current number does not receive SMS after 2 minutes.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode

Example Response

{
  "success": true,
  "data": {
    "id": "ACT9M2K8",
    "orderCode": "ACT9M2K8",
    "phone": "84912345678",
    "status": "WAIT_CODE"
  }
}

POST/api/otp/activations/{id}/cancel

Number rental & code API

Cancel Rental & 100% Automatic Refund

Cancel rental when no OTP has arrived yet. 100% of funds are automatically refunded to your wallet immediately.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode

Example Response

{
  "success": true,
  "status": "REFUNDED",
  "message": "Hủy kích hoạt thành công, số dư đã được hoàn lại.",
  "balanceAfter": 250000
}

POST/api/otp/activations/{id}/finish

Number rental & code API

Mark Rental Order as Finished

Mark the rental as finished once you have successfully received the needed OTP, closing the order.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode

Example Response

{
  "success": true,
  "message": "Đơn hàng đã được đánh dấu hoàn tất thành công."
}

GET/api/otp/activations/{id}/reactivate/options

Number rental & code API

Check Number Reactivation Options

Check whether the phone number from a previous completed order is still available to receive new OTP codes.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode of the previous order

Example Response

{
  "success": true,
  "available": true,
  "phone": "84931002233",
  "service": "tg",
  "durations": [
    {
      "duration": 20,
      "price": {
        "sellingVnd": 4000,
        "sellingUsd": 0.15
      }
    }
  ]
}

POST/api/otp/activations/{id}/reactivate

Number rental & code API

Reactivate Previously Rented Phone Number

Purchase the exact same phone number from a previous order to receive a new OTP. A new order is created.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode of the previous order (Path parameter)
duration	number	Optional	Reactivation duration in minutes (default: 20)

Request Body (JSON)

{
  "duration": 20
}

Example Response

{
  "success": true,
  "message": "Kích hoạt lại số thành công",
  "activation": {
    "id": "ACT7N1X2",
    "orderCode": "ACT7N1X2",
    "phone": "84931002233",
    "service": "tg",
    "status": "WAIT_CODE",
    "price": {
      "sellingVnd": 4000,
      "sellingUsd": 0.15
    },
    "createdAt": "2026-10-06T09:00:00.000Z"
  }
}

GET/api/otp/durations

Number rental & code API

Long-Term Rental Duration Plans

Query duration packages for long-term rentals (4h, 24h, 3 days, 7 days, etc.) with available inventory and VIP discounted prices.

Parameters

Field	Type	Required	Description
service	string	Required	Service code (e.g. tg, wa, fb...)
country	number \| string	Required	Country ID (e.g. 10, 1, 6...)
verificationType	string	Optional	'sms' (default) or 'call'

Example Response

{
  "success": true,
  "tier": 0,
  "data": [
    {
      "id": "4h",
      "durationMinutes": 240,
      "durationHours": 4,
      "label": "4 giờ",
      "type": "rent",
      "count": 1500,
      "prices": {
        "sellingUsd": 0.45,
        "sellingVnd": 12000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "id": "24h",
      "durationMinutes": 1440,
      "durationHours": 24,
      "label": "1 ngày (24h)",
      "type": "rent",
      "count": 1200,
      "prices": {
        "sellingUsd": 0.8,
        "sellingVnd": 21000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "id": "72h",
      "durationMinutes": 4320,
      "durationHours": 72,
      "label": "3 ngày (72h)",
      "type": "rent",
      "count": 800,
      "prices": {
        "sellingUsd": 2.2,
        "sellingVnd": 58000,
        "tier": 0,
        "discountPercent": 0
      }
    },
    {
      "id": "168h",
      "durationMinutes": 10080,
      "durationHours": 168,
      "label": "7 ngày (1 tuần)",
      "type": "rent",
      "count": 500,
      "prices": {
        "sellingUsd": 4.5,
        "sellingVnd": 118000,
        "tier": 0,
        "discountPercent": 0
      }
    }
  ]
}

POST/api/otp/buy

Number rental & code API

Rent Long-Term Dedicated Number

Create long-term rental order with duration in minutes (e.g. 1440 = 24h). Allows receiving unlimited OTP codes during the rental period.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Parameters

Field	Type	Required	Description
service	string	Required	Service code (e.g. tg, wa, fb...)
country	number \| string	Required	Country ID (e.g. 10, 1, 6...)
duration	number	Required	Rental duration in minutes (e.g. 240 = 4h, 1440 = 1 day, 4320 = 3 days, 10080 = 7 days)
verificationType	string	Optional	'sms' (default) or 'call'
operator	string	Optional	Target telco operator (default: 'any')

Request Body (JSON)

{
  "service": "tg",
  "country": 10,
  "duration": 1440,
  "verificationType": "sms",
  "operator": "any"
}

Example Response

{
  "success": true,
  "tier": 0,
  "balanceAfter": 229000,
  "data": [
    {
      "id": "ACT9L0P1",
      "orderCode": "ACT9L0P1",
      "phone": "84988776655",
      "service": "tg",
      "country": "10",
      "status": "WAIT_CODE",
      "price": {
        "sellingUsd": 0.8,
        "sellingVnd": 21000,
        "tier": 0,
        "discountPercent": 0
      },
      "createdAt": "2026-10-06T08:00:00.000Z",
      "expiredAt": "2026-10-07T08:00:00.000Z"
    }
  ]
}

GET/api/otp/activations/{id}/prolong/options

Number rental & code API

Check Prolongation Options for Active Rental

View available duration extension options and pricing for an active rented phone number.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode of the active rental

Example Response

{
  "success": true,
  "orderCode": "ACT9L0P1",
  "phone": "84988776655",
  "currentExpiresAt": "2026-10-07T08:00:00.000Z",
  "options": [
    {
      "duration": 1440,
      "label": "Gia hạn thêm 1 ngày (24h)",
      "prices": {
        "sellingVnd": 21000,
        "sellingUsd": 0.8
      }
    },
    {
      "duration": 4320,
      "label": "Gia hạn thêm 3 ngày (72h)",
      "prices": {
        "sellingVnd": 58000,
        "sellingUsd": 2.2
      }
    }
  ]
}

POST/api/otp/activations/{id}/prolong

Number rental & code API

Prolong Active Phone Rental

Extend rental duration for an active phone number. The expiration date (expiredAt) will be updated accordingly.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode of the active rental (Path parameter)
duration	number	Required	Extension duration in minutes (e.g. 1440 for 24h, 4320 for 3 days)

Request Body (JSON)

{
  "duration": 1440
}

Example Response

{
  "success": true,
  "message": "Gia hạn thời gian thuê số thành công",
  "data": {
    "id": "ACT9L0P1",
    "phone": "84988776655",
    "prolongMinutes": 1440,
    "newExpiredAt": "2026-10-08T08:00:00.000Z",
    "price": {
      "sellingVnd": 21000,
      "sellingUsd": 0.8
    },
    "balanceAfter": 208000
  }
}

GET/api/otp/activations/{id}/prolong/history

Number rental & code API

Rental Prolongation History

Get list of past successful prolongation events for a rented phone number.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string	Required	System orderCode

Example Response

{
  "success": true,
  "data": [
    {
      "id": "prolong_1",
      "duration": 1440,
      "priceVnd": 21000,
      "prolongedAt": "2026-10-06T12:00:00.000Z",
      "newExpiredAt": "2026-10-08T08:00:00.000Z"
    }
  ]
}

Email rental API

5 endpoints

GET/api/email-otp/offers

Email rental API

List Email Domains & Pricing

Get available email domains (gmail.com, outlook.com, mail.com,...) for the target service.

Parameters

Field	Type	Required	Description
site	string	Required	Target website name (e.g. telegram.com, openai.com...)

Example Response

{
  "success": true,
  "site": "telegram.com",
  "tier": 0,
  "data": [
    {
      "domain": "email.com",
      "count": 617667,
      "price": {
        "sellingVnd": 200,
        "sellingUsd": 0.0075
      }
    },
    {
      "domain": "gmail.com",
      "count": 125000,
      "price": {
        "sellingVnd": 1500,
        "sellingUsd": 0.057
      }
    }
  ]
}

POST/api/email-otp/buy

Email rental API

Rent Temporary Email for OTP

Rent a temporary email mailbox to receive activation verification codes. Supports maxPrice ceiling.

Headers

x-api-key	your_api_key_here	API Key
Content-Type	application/json	application/json

Request Body (JSON)

{
  "site": "telegram.com",
  "domain": "email.com",
  "maxPrice": 500
}

Example Response

{
  "success": true,
  "data": {
    "id": 774819,
    "email": "[email protected]",
    "status": "WAIT",
    "price": {
      "sellingVnd": 200,
      "sellingUsd": 0.0075,
      "tier": 0
    },
    "createdAt": "2026-10-06T08:30:00.000Z"
  }
}

GET/api/email-otp/activations/{id}

Email rental API

Get Email OTP Code & Full Message Content

Query mailbox status. When email arrives, extracted OTP (value) and full text message are returned.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string \| number	Required	Email rental ID (e.g. 774819)

Example Response

{
  "success": true,
  "data": {
    "id": 774819,
    "email": "[email protected]",
    "status": "SUCCESS",
    "value": "449102",
    "message": "Telegram code: 449102. You can also tap this link to log in...",
    "createdAt": "2026-10-06T08:30:00.000Z"
  }
}

POST/api/email-otp/activations/{id}/cancel

Email rental API

Cancel Email Rental & 100% Refund

Cancel email rental if no email arrived and receive an instant 100% refund into wallet.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string \| number	Required	Email rental ID

Example Response

{
  "success": true,
  "message": "Huỷ đơn thuê email thành công, số dư đã được hoàn lại.",
  "balanceAfter": 250000
}

POST/api/email-otp/activations/{id}/reorder

Email rental API

Reorder / Reuse Previous Email Mailbox

Reorder the exact same email mailbox previously used to receive additional verification codes.

Headers

x-api-key

your_api_key_here

API Key

Parameters

Field	Type	Required	Description
id	string \| number	Required	Previous email rental ID

Example Response

{
  "success": true,
  "message": "Gia hạn / Thuê lại email thành công",
  "data": {
    "id": 774825,
    "site": "telegram.com",
    "domain": "email.com",
    "email": "[email protected]",
    "status": "WAIT",
    "price": {
      "sellingVnd": 200,
      "sellingUsd": 0.0075,
      "tier": 0
    },
    "createdAt": "2026-10-06T09:15:00.000Z"
  }
}

Email purchase API

3 endpoints

GET/api/mail/products

Email purchase API

Mail: List Products

System API for listing mail products. Provider details stay internal; clients use only this website API key.

Headers

x-api-key

your_website_api_key

Website API key

Parameters

Field	Type	Required	Description
status	1	Optional	Only active products

Example Response

{
  "success": true,
  "data": [
    {
      "slug": "email-gmail",
      "name": "Gmail Fresh",
      "price": 15000,
      "stock": 50
    }
  ]
}

POST/api/mail/buy

Email purchase API

Mail: Purchase Email

Purchase mail through the system API. Website wallet balance is deducted automatically.

Headers

x-api-key

your_website_api_key

Website API key

Parameters

Field	Type	Required	Description
product_slug	string	Required	Product slug
quantity	1..10000	Required	Mail quantity

Request Body (JSON)

{
  "product_slug": "email-gmail",
  "quantity": 1
}

Example Response

{
  "success": true,
  "data": {
    "order_code": "ORD-20251218-ABC123",
    "quantity": 1,
    "emails": [
      {
        "email": "[email protected]"
      }
    ]
  }
}

POST/api/mail/read

Email purchase API

Mail: Read Outlook Inbox

Read a purchased mailbox through the system API. Provider and credentials stay internal.

Headers

x-api-key

your_website_api_key

Website API key

Request Body (JSON)

{
  "hotmail": "[email protected]",
  "folder": "Inbox",
  "limit": 10,
  "unread_only": false
}

Example Response

{
  "success": true,
  "data": {
    "total": 1,
    "emails": [
      {
        "subject": "Your verification code",
        "sender_email": "[email protected]",
        "body_preview": "Your code is 312578..."
      }
    ]
  }
}

Proxy API

4 endpoints

GET/api/proxy/download

Proxy API

Download Proxy List

Download proxies from your order. A Clerk session is currently required.

Parameters

Field	Type	Required	Description
order_id	string	Required	Proxy order ID or code
mode	direct \| backbone	Optional	Proxy mode, defaults to direct
format	string	Optional	ip:port:user:pass, user:pass@ip:port, or ip:port

Example Response

1.2.3.4:8080:username:password

GET/api/proxy/countries

Proxy API

List Proxy Countries

Get countries available for proxy purchase, including available IP count when provided.

Example Response

{
  "success": true,
  "data": [
    {
      "code": "US",
      "name": "United States",
      "proxyCount": 1200
    }
  ]
}

GET/api/proxy/prices?proxy_type=shared&proxy_count=10&countries=US,SG

Proxy API

Check Proxy Price

Calculate selling price by proxy type, count, countries, bandwidth, and VIP tier. `countries` is a comma-separated ISO 2-letter code list.

Headers

x-api-key

your_api_key_here

Optional, applies VIP pricing

Parameters

Field	Type	Required	Description
proxy_type	string	Required	Proxy type, such as `shared` or `dedicated`
proxy_count	integer	Required	IP count, from 1 to 10,000
countries	string	Optional	Comma-separated country codes
bandwidth_limit	integer	Optional	Bandwidth limit
term	`monthly` \| `yearly`	Optional	Billing term; defaults to `monthly`

Example Response

{
  "success": true,
  "tier": 0,
  "data": {
    "sellingVnd": 125000,
    "sellingUsd": 5,
    "proxyCount": 10
  }
}

POST/api/proxy/buy

Proxy API

Purchase Proxy

Purchase a proxy plan and deduct its cost from the API key owner wallet.

Headers

x-api-key

your_api_key_here

Account API Key

Request Body (JSON)

{
  "proxyType": "shared",
  "proxyCount": 10,
  "bandwidthLimit": 100,
  "countries": [
    "US",
    "SG"
  ]
}

Example Response

{
  "success": true,
  "data": {
    "orderCode": "PRX-ABC123",
    "proxyCount": 10,
    "balanceAfter": 750000
  }
}

SMS-Activate Compatible API

18 endpoints

GET/stubs/handler_api.php?action=getBalance

SMS-Activate Compatible API

SMS-Activate: Check Account Balance (getBalance)

Returns available wallet balance converted to USD as a raw text string ACCESS_BALANCE:<amount>. Fully compatible with all software integrated with SMS-Activate.

Parameters

Field	Type	Required	Description
api_key	string	Required	Your account API key
action	string	Required	Action name: getBalance

Example Response

ACCESS_BALANCE:25.50

GET/stubs/handler_api.php?action=getNumber

SMS-Activate Compatible API

SMS-Activate: Order Phone Number (getNumber - Text)

Requests a new phone number for the specified service and country. Returns raw string ACCESS_NUMBER:<activation_id>:<phone>. Automatically deducts wallet balance using system pricing and customer VIP discount.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getNumber
service	string	Required	Service code (e.g. tg, wa, ig, go, fb, vi, lf...)
country	number	Required	Country ID (e.g. 10 - Vietnam, 6 - Indonesia, 2 - Kazakhstan, 12 - USA...)
operator	string	Optional	Desired telecom operator (e.g. viettel, mobifone, vinaphone)
maxPrice	number	Optional	Maximum price you are willing to pay (USD). If actual selling price is higher, order is cancelled and returns NO_NUMBERS.

Example Response

ACCESS_NUMBER:819284712:84981234567

GET/stubs/handler_api.php?action=getNumberV2

SMS-Activate Compatible API

SMS-Activate: Order Phone Number (getNumberV2 - JSON)

Orders a new phone number and returns structured JSON with activation ID, phone number, cost (USD), country code, expiry timestamp, and canGetAnotherSms flag.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getNumberV2
service	string	Required	Service code (tg, wa, fb, go...)
country	number	Required	Country ID

Example Response

{
  "activationId": "819284712",
  "phoneNumber": "84981234567",
  "activationCost": 0.45,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T10:00:00.000Z",
  "activationEndTime": "2026-04-01T10:20:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 1,
  "serviceCode": "tg",
  "status": 4
}

GET/stubs/handler_api.php?action=setStatus

SMS-Activate Compatible API

SMS-Activate: Change Activation Status (setStatus)

Lifecycle management: status=1 (ACCESS_READY: number ready), status=3 (ACCESS_RETRY_GET: request another code), status=6 (ACCESS_ACTIVATION: complete order), status=8 (ACCESS_CANCEL: cancel and 100% refund).

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: setStatus
id	string	Required	Activation ID or internal orderCode
status	number	Required	1 (ready), 3 (retry next code), 6 (finish), 8 (cancel & refund)

Example Response

ACCESS_RETRY_GET

GET/stubs/handler_api.php?action=getStatus

SMS-Activate Compatible API

SMS-Activate: Get Activation Status & OTP (getStatus - Text)

Checks activation status. When SMS arrives returns STATUS_OK:<code>. While waiting returns STATUS_WAIT_CODE. If cancelled returns STATUS_CANCEL. Automatically syncs latest SMS.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getStatus
id	string	Required	Activation ID or orderCode

Example Response

STATUS_OK:482910

GET/stubs/handler_api.php?action=getStatusV2

SMS-Activate Compatible API

SMS-Activate: Get Status & OTP Details (getStatusV2 - JSON)

Returns JSON data with extracted OTP code, sender phone/service name, full SMS text, and delivery timestamp.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getStatusV2
id	string	Required	Activation ID

Example Response

{
  "verificationType": "sms",
  "data": {
    "id": "3416693217",
    "phoneFrom": "Telegram",
    "code": "482910",
    "text": "Telegram code 482910",
    "service": "tg",
    "date": "2026-04-01T10:02:15.000Z",
    "type": "sms"
  }
}

GET/stubs/handler_api.php?action=getActiveActivations

SMS-Activate Compatible API

SMS-Activate: List Active Activations (getActiveActivations)

Retrieves all currently active orders waiting for code (WAIT_CODE) or already received code (OK) for your account.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getActiveActivations

Example Response

{
  "status": "success",
  "data": [
    {
      "activationId": "819284715",
      "serviceCode": "tg",
      "phoneNumber": "84981234567",
      "activationCost": 0.45,
      "activationStatus": "4",
      "smsCode": "482910",
      "smsText": "Telegram code 482910",
      "activationTime": "2026-04-01 10:00:00",
      "countryCode": "10",
      "canGetAnotherSms": "1",
      "currency": 840,
      "verificationType": "sms",
      "subtype": 1
    }
  ]
}

GET/stubs/handler_api.php?action=getHistory

SMS-Activate Compatible API

SMS-Activate: Activation History (getHistory)

Retrieves historical list of recent activation orders including OTP messages, costs, and final statuses.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getHistory

Example Response

[
  {
    "id": "819284715",
    "date": "2026-04-01 10:00:00",
    "phone": "84981234567",
    "sms": {
      "code": "482910",
      "text": "Telegram code 482910",
      "date": "2026-04-01T10:02:15.000Z"
    },
    "cost": 0.45,
    "status": "OK",
    "currency": 840
  }
]

GET/stubs/handler_api.php?action=getCountries

SMS-Activate Compatible API

SMS-Activate: List Supported Countries (getCountries)

Returns all available countries with ID, Russian, English, and Chinese names. Disabled countries are automatically excluded.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getCountries

Example Response

[
  {
    "id": 10,
    "rus": "Вьетнам",
    "eng": "Vietnam",
    "chn": "越南",
    "visible": 1,
    "retry": 1
  },
  {
    "id": 6,
    "rus": "Индонезия",
    "eng": "Indonesia",
    "chn": "印度尼西亚",
    "visible": 1,
    "retry": 1
  },
  {
    "id": 2,
    "rus": "Казахстан",
    "eng": "Kazakhstan",
    "chn": "哈萨克斯坦",
    "visible": 1,
    "retry": 1
  }
]

GET/stubs/handler_api.php?action=getServicesList

SMS-Activate Compatible API

SMS-Activate: List Available Services (getServicesList)

Returns service codes and corresponding display names. Disabled services are automatically excluded.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getServicesList
country	number	Optional	Filter by country ID (optional)

Example Response

{
  "status": "success",
  "services": [
    {
      "code": "tg",
      "name": "Telegram"
    },
    {
      "code": "wa",
      "name": "WhatsApp"
    },
    {
      "code": "go",
      "name": "Google, YouTube, Gmail"
    },
    {
      "code": "fb",
      "name": "Facebook"
    },
    {
      "code": "ig",
      "name": "Instagram"
    }
  ]
}

GET/stubs/handler_api.php?action=getOperators

SMS-Activate Compatible API

SMS-Activate: List Telecom Operators (getOperators)

Retrieves supported telecom operators for the specified country.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getOperators
country	number	Required	Country ID (e.g. 10 for Vietnam)

Example Response

{
  "status": "success",
  "countryOperators": {
    "10": [
      "viettel",
      "vinaphone",
      "mobifone",
      "vietnamobile",
      "itelecom"
    ]
  }
}

GET/stubs/handler_api.php?action=getPrices

SMS-Activate Compatible API

SMS-Activate: Pricing & Inventory Matrix (getPrices)

Returns real-time selling prices and available count per country and service. Prices are automatically calculated with system margin and your VIP Loyalty Tier discount.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getPrices
country	number	Optional	Country ID to filter (optional)
service	string	Optional	Service code to filter (optional)

Example Response

{
  "6": {
    "tg": {
      "cost": 0.38,
      "count": 5400
    },
    "wa": {
      "cost": 0.42,
      "count": 2100
    }
  },
  "10": {
    "tg": {
      "cost": 0.45,
      "count": 1250
    },
    "wa": {
      "cost": 0.55,
      "count": 820
    },
    "go": {
      "cost": 0.35,
      "count": 3400
    }
  }
}

GET/stubs/handler_api.php?action=getTopCountriesByService

SMS-Activate Compatible API

SMS-Activate: Top Countries by Inventory (getTopCountriesByService)

Retrieves top countries with highest number availability and optimal selling price for a given service.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getTopCountriesByService
service	string	Required	Service code (e.g. tg)

Example Response

[
  {
    "country": 6,
    "count": 5477,
    "price": 0.38,
    "retail_price": 0.38
  },
  {
    "country": 10,
    "count": 1250,
    "price": 0.45,
    "retail_price": 0.45
  },
  {
    "country": 2,
    "count": 980,
    "price": 0.52,
    "retail_price": 0.52
  }
]

GET/stubs/handler_api.php?action=getAllSms

SMS-Activate Compatible API

SMS-Activate: Get All Received SMS Messages (getAllSms)

Retrieves an array of all SMS messages and FlashCall verifications received for this phone number during the rental.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getAllSms
id	string	Required	Activation ID

Example Response

{
  "data": [
    {
      "id": "3416693217",
      "phoneFrom": "Telegram",
      "code": "123456",
      "text": "Telegram code 123456",
      "service": "tg",
      "date": "2026-04-01T10:02:15.000Z",
      "type": "sms"
    },
    {
      "id": "3416693218",
      "phoneFrom": "Telegram",
      "code": "654321",
      "text": "Telegram code 654321",
      "service": "tg",
      "date": "2026-04-01T10:05:30.000Z",
      "type": "sms"
    }
  ]
}

GET/stubs/handler_api.php?action=serviceCountRent

SMS-Activate Compatible API

SMS-Activate: Long-Term Rental Inventory & Pricing (serviceCountRent)

Queries long-term rental durations (e.g. 2h, 4h, 24h, 72h, 168h) with stock counts and VIP discounted pricing.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: serviceCountRent
country	number	Optional	Country ID to query

Example Response

{
  "10": {
    "4": {
      "count": 850,
      "price": 0.85,
      "retail_price": 0.85
    },
    "24": {
      "count": 620,
      "price": 1.5,
      "retail_price": 1.5
    },
    "72": {
      "count": 310,
      "price": 3.2,
      "retail_price": 3.2
    },
    "168": {
      "count": 180,
      "price": 6,
      "retail_price": 6
    }
  }
}

GET/stubs/handler_api.php?action=getRentNumber

SMS-Activate Compatible API

SMS-Activate: Purchase Long-Term Rent Number (getRentNumber)

Rents a phone number for hours or days (duration: 4, 24, 72, 168...). Can receive unlimited consecutive OTP messages throughout the period.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: getRentNumber
service	string	Required	Service code (e.g. tg)
country	number	Required	Country ID
duration	number	Required	Rental duration in hours (e.g. 24 for 1 day, 168 for 7 days)

Example Response

{
  "activationId": "819284720",
  "phoneNumber": "84985556677",
  "activationCost": 1.5,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T10:00:00.000Z",
  "activationEndTime": "2026-04-02T10:00:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 2,
  "serviceCode": "tg",
  "status": 4
}

POST/stubs/handler_api.php?action=prolong

SMS-Activate Compatible API

SMS-Activate: Extend Long-Term Rental (prolong)

Extends rental duration for an active number before it expires. Extension fee is automatically deducted from account wallet.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: prolong
id	string	Required	Activation ID
duration	number	Required	Hours to extend (e.g. 24)

Example Response

{
  "activationId": "819284725",
  "phoneNumber": "84985556677",
  "activationCost": 1.5,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T10:00:00.000Z",
  "activationEndTime": "2026-04-03T10:00:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 2,
  "serviceCode": "tg",
  "status": 4
}

POST/stubs/handler_api.php?action=reactivate

SMS-Activate Compatible API

SMS-Activate: Reactivate Expired Number (reactivate)

Re-rents the exact phone number from a previously finished order to receive new OTP if still available at provider.

Parameters

Field	Type	Required	Description
api_key	string	Required	Account API key
action	string	Required	Action name: reactivate
id	string	Required	Activation ID of the past order

Example Response

{
  "activationId": "819284730",
  "phoneNumber": "84985556677",
  "activationCost": 0.45,
  "currency": 840,
  "countryCode": 10,
  "countryPhoneCode": 84,
  "canGetAnotherSms": true,
  "activationTime": "2026-04-01T15:00:00.000Z",
  "activationEndTime": "2026-04-01T15:20:00.000Z",
  "activationOperator": "any",
  "verificationType": "sms",
  "subtype": 1,
  "serviceCode": "tg",
  "status": 4
}

Order Status Codes

Standard lifecycle status for phone and email OTP rentals

WAIT_CODEWaiting for SMS or email OTP to be delivered

OK / SUCCESSOTP received successfully with extracted code and full message

REFUNDEDOrder cancelled, 100% of payment refunded to wallet

FINISHEDOrder completed and rental cycle ended

HTTP Status Codes & Error Handling

JSON format: { "success": false, "error": "..." }

200 OKRequest successful, data returned in the data field.

400 Bad RequestInvalid parameters, missing required fields, or service temporarily out of stock.

401 UnauthorizedMissing or invalid API Key. Please check the x-api-key header.

402 Payment RequiredInsufficient wallet balance to pay for the order. Please top up funds.