Developer Documentation

API Documentation & Integration Guide

All API endpoints use GET method for easy integration.

Easily integrate into your software, automation bots, or custom backend. Fully supports standard REST JSON and one-line URL protocol.

API Authentication (API Key)

Bước 1: Chọn dịch vụ

GET /prices?service=tg&country=vn

Kiểm tra số lượng và giá thấp nhất.

Bước 2: Mua số

GET /activations/create?service=tg&country=vn

Nhận số điện thoại và ID đơn hàng.

Bước 3: Nhận mã OTP

GET /activations/{id}

Hoặc nhận tự động qua Webhook.

Bước 4: Hoàn thành

GET /activations/{id}/complete

Đóng đơn sau khi nhập mã thành công.

Nếu không có OTP: Hủy

GET /activations/{id}/cancel

Tiền sẽ được tự động hoàn 100% vào ví.

Bước 1: Xem giá Email

GET /mail-prices?service=openai

Kiểm tra domain và mức giá.

Bước 2: Mua Email

GET /mail-activations/create?service=openai

Nhận địa chỉ email tạm thời.

Bước 3: Lấy mã OTP Mail

GET /mail-activations/{id}

Lấy mã xác nhận từ hòm thư.

Bước 4: Hoàn thành / Hủy

GET /mail-activations/{id}/complete

Hoặc gọi cancel để nhận lại tiền.

View JSON Spec

01 Import vào Postman / Insomnia:

Mở ứng dụng Postman hoặc Insomnia.
Bấm nút Import ở góc trên bên trái.
Dán đường link URL OpenAPI ở trên vào và bấm Import.
Toàn bộ 21 API kèm tham số mẫu sẽ được tạo tự động trong 1 Collection.

02 Tự động sinh Client SDK:

Dùng CLI để tự sinh mã nguồn client cho dự án (Python, TypeScript, PHP, Go, C#...):

npx @openapitools/openapi-generator-cli generate \
  -i https://36otp.com/openapi.json?locale=en \
  -g python -o ./sms-client

Check Account Balance

Kiểm tra số dư ví USD

Parameters

Parameter	Type	Required	Description
api_key	string	No	API Key của bạn (có thể truyền qua query ?api_key=... hoặc header X-API-Key)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "balance": "100.500000",
    "currency": "USD"
  }
}

SMS Service Catalog

Danh sách dịch vụ SMS hỗ trợ

Parameters

Parameter	Type	Required	Description
search	string	No	Từ khóa tìm kiếm theo tên hoặc mã dịch vụ (ví dụ: telegram, tg, whatsapp)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "id": 1,
      "code": "tg",
      "name": "Telegram",
      "popular_rank": 1
    }
  ]
}

Danh sách quốc gia hỗ trợ

Parameters

Parameter	Type	Required	Description
search	string	No	Từ khóa tìm kiếm theo tên hoặc mã quốc gia (ví dụ: vietnam, vn)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "id": 1,
      "code": "vn",
      "name": "Vietnam",
      "phone_code": "84"
    }
  ]
}

Bảng giá SMS theo dịch vụ và quốc gia

Parameters

Parameter	Type	Required	Description
service	string	No	Mã dịch vụ (ví dụ: tg, wa)
country	string	No	Mã quốc gia (ví dụ: vn, us, id)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "service": "tg",
      "country": "vn",
      "price": "0.250000",
      "currency": "USD",
      "count": 142
    }
  ]
}

Chi tiết offers theo từng nhà mạng / provider

Parameters

Parameter	Type	Required	Description
service	string	Yes	Mã dịch vụ (ví dụ: tg)
country	string	Yes	Mã quốc gia (ví dụ: vn)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "provider": "telecom_vn",
      "price": "0.250000",
      "count": 95
    }
  ]
}

SMS Number Rentals

Danh sách các đơn thuê số SMS của bạn

Parameters

Parameter	Type	Required	Description
status	string	No	Lọc theo trạng thái: pending, ready, code_received, completed, cancelled
page	integer	No	Số trang (mặc định 1)
per_page	integer	No	Số lượng mỗi trang (mặc định 15, tối đa 50)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "id": "act_9a8b7c6d5e",
      "service": "tg",
      "country": "vn",
      "phone_number": "84987654321",
      "status": "code_received",
      "price": "0.250000",
      "last_code": "123456",
      "expires_at": "2026-09-11T12:00:00Z"
    }
  ],
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

Thuê số SMS mới (Đặt mua số)

Parameters

Parameter	Type	Required	Description
service	string	Yes	Mã dịch vụ (ví dụ: tg, wa, google)
country	string	Yes	Mã quốc gia (ví dụ: vn, us)
provider	string	No	Mã nhà mạng lấy từ /api/v1/offers (ví dụ: 3193). Khi chỉ định, hệ thống thuê đúng nhà mạng này với đúng giá của offer; nếu nhà mạng hết số sẽ trả NO_NUMBERS thay vì tự chuyển sang nhà mạng khác
max_price	string	No	Giá bán tối đa bạn chấp nhận trả (theo bảng giá của hệ thống, ví dụ: 0.30)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "service": "tg",
    "country": "vn",
    "phone_number": "84987654321",
    "status": "pending",
    "price": "0.250000",
    "currency": "USD",
    "expires_at": "2026-09-11T12:00:00Z"
  }
}

Chi tiết đơn & Lấy mã OTP SMS

Parameters

Parameter	Type	Required	Description
activation	string	Yes	ID của đơn thuê (ví dụ: act_9a8b7c6d5e)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "code_received",
    "phone_number": "84987654321",
    "last_code": "123456",
    "messages": [
      {
        "code": "123456",
        "text": "Telegram code 123456",
        "received_at": "2026-09-11T11:45:00Z"
      }
    ]
  }
}

Báo sẵn sàng nhận tin nhắn

Parameters

Parameter	Type	Required	Description
activation	string	Yes	ID đơn thuê

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "ready"
  }
}

Yêu cầu gửi lại mã SMS mới (lần 2)

Parameters

Parameter	Type	Required	Description
activation	string	Yes	ID đơn thuê

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "ready"
  }
}

Hoàn thành đơn thuê số

Parameters

Parameter	Type	Required	Description
activation	string	Yes	ID đơn thuê

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "completed"
  }
}

Hủy đơn thuê & Hoàn tiền vào ví USD

Parameters

Parameter	Type	Required	Description
activation	string	Yes	ID đơn thuê

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "act_9a8b7c6d5e",
    "status": "cancelled",
    "refunded": true,
    "refund_amount": "0.250000"
  }
}

Email Service Catalog

Danh mục dịch vụ Email hỗ trợ

Parameters

Parameter	Type	Required	Description
search	string	No	Từ khóa tìm kiếm (ví dụ: openai, discord)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "id": 12,
      "code": "openai",
      "name": "OpenAI / ChatGPT"
    }
  ]
}

Danh sách domain email sẵn có

Parameters

Parameter	Type	Required	Description
service	string	No	Lọc theo mã dịch vụ

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "id": 1,
      "domain": "mailto.plus"
    }
  ]
}

Bảng giá dịch vụ Email

Parameters

Parameter	Type	Required	Description
service	string	No	Mã dịch vụ (ví dụ: openai)
domain	string	No	Domain email cụ thể

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "service": "openai",
      "domain": "mailto.plus",
      "price": "0.100000",
      "count": 850
    }
  ]
}

Email Rentals

Danh sách đơn thuê Email của bạn

Parameters

Parameter	Type	Required	Description
status	string	No	Lọc trạng thái: pending, ready, code_received, completed, cancelled
page	integer	No	Số trang (mặc định 1)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": [
    {
      "id": "mact_11223344",
      "service": "openai",
      "email_address": "[email protected]",
      "status": "code_received",
      "price": "0.100000"
    }
  ]
}

Thuê Email mới

Parameters

Parameter	Type	Required	Description
service	string	Yes	Mã dịch vụ email (ví dụ: openai, discord)
domain	string	No	Domain mong muốn (tùy chọn)
quantity	integer	No	Số lượng muốn thuê (1-100, mặc định 1)
max_price	string	No	Mức giá tối đa chấp nhận (ví dụ: 0.15)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "mact_11223344",
    "service": "openai",
    "email_address": "[email protected]",
    "status": "pending",
    "price": "0.100000",
    "currency": "USD",
    "expires_at": "2026-09-11T12:00:00Z"
  }
}

Chi tiết đơn email & Lấy mã OTP

Parameters

Parameter	Type	Required	Description
mailActivation	string	Yes	ID đơn thuê email (ví dụ: mact_11223344)

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "mact_11223344",
    "status": "code_received",
    "email_address": "[email protected]",
    "last_code": "859402",
    "messages": [
      {
        "code": "859402",
        "subject": "Your OpenAI verification code",
        "from": "[email protected]",
        "received_at": "2026-09-11T11:48:00Z"
      }
    ]
  }
}

Yêu cầu nhận lại email mới

Parameters

Parameter	Type	Required	Description
mailActivation	string	Yes	ID đơn thuê email

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "mact_11223344",
    "status": "ready"
  }
}

Hoàn thành đơn thuê email

Parameters

Parameter	Type	Required	Description
mailActivation	string	Yes	ID đơn thuê email

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "mact_11223344",
    "status": "completed"
  }
}

Hủy đơn email & Hoàn tiền vào ví USD

Parameters

Parameter	Type	Required	Description
mailActivation	string	Yes	ID đơn thuê email

Request URL (Full Path)

Open in browser

Sample response

{
  "data": {
    "id": "mact_11223344",
    "status": "cancelled",
    "refunded": true,
    "refund_amount": "0.100000"
  }
}

Webhook for automatic code delivery

Real-time Push

⚡ Use Webhooks instead of polling

Instead of repeatedly calling the API to check for OTP (wasting rate limit, adding latency), register a Webhook to receive codes instantly when they arrive. Saves 95% of API calls.

Signature Verification

Each outbound webhook contains header X-OTP-Signature computed using HMAC-SHA256 of timestamp + "." + body:

<?php
$secret = 'YOUR_WEBHOOK_SECRET';
$timestamp = $_SERVER['HTTP_X_OTP_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_OTP_SIGNATURE'] ?? '';
$payload = file_get_contents('php://input');

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Xử lý OTP: $data['activation']['last_code']
http_response_code(200);
echo json_encode(['received' => true]);

import hmac
import hashlib

def verify_webhook(request_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    signed_payload = f"{timestamp}.".encode() + request_body
    expected = "sha256=" + hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# Flask / FastAPI:
# is_valid = verify_webhook(await request.body(), request.headers.get("X-OTP-Timestamp"), request.headers.get("X-OTP-Signature"), WEBHOOK_SECRET)

const crypto = require('crypto');

function verifyWebhook(bodyBuffer, timestamp, signatureHeader, secret) {
    const expected = 'sha256=' + crypto.createHmac('sha256', secret)
        .update(`${timestamp}.${bodyBuffer.toString()}`)
        .digest('hex');
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}

// Express:
// const valid = verifyWebhook(req.rawBody, req.headers['x-otp-timestamp'], req.headers['x-otp-signature'], process.env.WEBHOOK_SECRET);

Event List

Event	Description
activation.created	Đơn thuê số SMS mới được khởi tạo thành công.
sms.received	Tin nhắn SMS chứa mã OTP vừa gửi đến số điện thoại.
activation.completed	Đơn thuê số hoàn tất thành công.
activation.cancelled	Đơn thuê số bị hủy và tiền hoàn vào ví.
mail_activation.code_received	Hòm thư email nhận được mã xác nhận OTP mới.

Retry Policy: System retries 5 times with backoff: immediately → 1 min → 5 min → 30 min → 2 hours.

API Error Codes

Order Status Descriptions

pending	Pending
ready	Ready to receive code
code_received	Code received
completed	Completed
cancelled	Cancelled & Refunded

API Error Codes

401 Unauthorized	API Key không hợp lệ hoặc đã bị vô hiệu hóa.
402 Payment Required	Số dư ví không đủ để thanh toán đơn hàng.
404 Not Found	Không tìm thấy đơn thuê hoặc dịch vụ tương ứng.
429 Too Many Requests	Vượt quá giới hạn gọi API (Rate Limit).

API Documentation & Integration Guide

API Authentication (API Key)

Quick Start: Rent a number & receive SMS OTP

Quick Start: Rent an email & receive email OTP

OpenAPI 3.0 JSON Spec (Postman / Insomnia / SDK)

01 Import vào Postman / Insomnia:

02 Tự động sinh Client SDK:

Check Account Balance

SMS Service Catalog

SMS Number Rentals

Email Service Catalog

Email Rentals

Webhook for automatic code delivery

⚡ Use Webhooks instead of polling

Signature Verification

Event List

API Error Codes

Order Status Descriptions

API Error Codes

Webhook Configuration

Recent Deliveries