Copied!
USAVerify Logo USAVerify Pro Worldwide API

Worldwide Numbers API Documentation

Automate 180+ countries, live prices, numbers allocation, and SMS OTP reception into your customer-facing website or bots.

API Authentication and Rate Limits

All requests require your unique API key passed as an HTTP Header (Authorization: Bearer <API_KEY>) or as a query parameter (?api_key=<API_KEY>). Standard rate limits permit up to 120 requests per minute with automated bursted scaling for reseller platforms.

🔑 Your API Key:

Worldwide Numbers API Endpoints

Explore the complete specification for balance inquiries, numbers ordering, multi-code SMS polling, and real-time webhook callbacks. For USA-only carrier activations, see our dedicated USA SMS API Documentation, or test orders interactively in the Worldwide Numbers Console.

Get Balance

Returns your current account balance in live USD.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getBalance
Parameters
api_key
Your secret USAVerify Developer API Key
action
getBalance
Answer
SMS-ACTIVATE FORMAT (text/plain)
ACCESS_BALANCE:54.20
REST JSON FORMAT
{
  "ok": true,
  "balance": 54.20,
  "currency": "USD"
}
Get phone number

Rents a virtual phone number for a specific country and service. Balance is reserved atomically.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumber&service=wa&country=16
Parameters
api_key
Your secret USAVerify Developer API Key
action
getNumber
service
Service code (e.g. wa for WhatsApp, tg for Telegram, openai for ChatGPT)
country
Country ID (e.g. 16 for UK, 187 for USA, 22 for Germany, 78 for Brazil)
Answer
SMS-ACTIVATE FORMAT (text/plain)
ACCESS_NUMBER:893120:447401234567
REST JSON FORMAT
{
  "ok": true,
  "order_id": "ww_1730305100",
  "activation_id": "893120",
  "phone": "447401234567",
  "price_usd": 0.45,
  "currency": "USD",
  "expiry_secs": 1200
}
Get SMS code

Checks the status of an active number rental to retrieve received verification codes. Poll every 3–5 seconds.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getStatus&id=893120
Parameters
api_key
Your secret API Key
action
getStatus
id
Activation ID returned by getNumber (e.g. 893120) or order_id
Answer
STATUS DELIVERED (text/plain)
STATUS_OK:849201
STATUS WAITING (text/plain)
STATUS_WAIT_CODE
Change of activation status

Changes the status of a number. Status 8 triggers an instant 100% automated refund if no code was received.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=setStatus&id=893120&status=8
Parameters
api_key
Your secret API Key
id
Activation ID
status
8 - Cancel order and refund balance 100%
6 - Complete activation successfully
3 - Request next SMS (resend)
Answer
CANCELLATION CONFIRMATION
ACCESS_CANCEL
COMPLETION CONFIRMATION
ACCESS_ACTIVATION
Get prices

Fetch live prices and available quantity for all services in a specific country.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices&country=16&service=wa
Parameters
api_key
Your API Key
country
Country ID (e.g. 16)
service
Service code (optional)
Answer (JSON - object in format)
{
  "16": {
    "wa": {
      "0.45": 480,
      "0.50": 120
    },
    "tg": {
      "0.35": 610
    }
  }
}
Services

Returns a complete list of all supported service names and their stable service codes to set up on your website.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getServicesList
Parameters
api_key
Your API Key
action
getServicesList
Answer (JSON - object in format)
{
  "status": "success",
  "services": [
    {
      "code": "wa",
      "name": "WhatsApp"
    },
    {
      "code": "tg",
      "name": "Telegram"
    },
    {
      "code": "openai",
      "name": "OpenAI / ChatGPT"
    },
    {
      "code": "go",
      "name": "Google, YouTube, Gmail"
    },
    {
      "code": "ig",
      "name": "Instagram"
    },
    {
      "code": "kt",
      "name": "KakaoTalk"
    }
  ]
}
List of countries

Returns all supported countries with numeric IDs, ISO codes, and multi-language names to display on your customer storefront.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getCountries
Parameters
api_key
Your API Key
action
getCountries
Answer (JSON - object in format)
{
  "16": {
    "id": 16,
    "rus": "Великобритания",
    "eng": "United Kingdom",
    "chn": "英国"
  },
  "187": {
    "id": 187,
    "rus": "США",
    "eng": "United States",
    "chn": "美国"
  },
  "22": {
    "id": 22,
    "rus": "Германия",
    "eng": "Germany",
    "chn": "德国"
  },
  "78": {
    "id": 78,
    "rus": "Бразилия",
    "eng": "Brazil",
    "chn": "巴西"
  },
  "1001": {
    "id": 1001,
    "rus": "Нигерия",
    "eng": "Nigeria",
    "chn": "尼日利亚"
  }
}
Top countries by service

Returns countries sorted by highest live stock and delivery success rate for a given service.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getTopCountriesByService&service=wa
Parameters
api_key
Your API Key
service
Service code (e.g. wa, tg)
Answer
[
  {"country": 16, "name": "United Kingdom", "count": 480, "price": 0.45},
  {"country": 22, "name": "Germany", "count": 310, "price": 0.50},
  {"country": 78, "name": "Brazil", "count": 290, "price": 0.35}
]
Get phone number v2

Extended phone number rental with route filtering and operator selection.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getNumberV2&service=wa&country=16&max_price=0.50
Answer (JSON)
{
  "status": "SUCCESS",
  "activationId": "893120",
  "phoneNumber": "447401234567",
  "activationCost": 0.45,
  "countryCode": "16"
}
Get full prices list v2

Returns complete global matrix of all countries and services with price tiers and stock counts in a single payload.

https://usaverifypro.com/stubs/handler_api.php?api_key=YOUR_API_KEY&action=getPrices&country=ALL
Answer
{
  "country_code": {
    "service_code": {
      "price": available_count
    }
  }
}
Notification via Webhook & Polling

Understand how OTP codes are delivered to your system.

Recommended Polling Architecture (Standard for 95% of Resellers)

In the SMS verification industry, standard reseller bots and SMM panels use Polling because carrier transmission takes 5 to 20 seconds. Poll getStatus every 3 to 5 seconds until received or timeout expires.

Inbound Webhook Handling

Our core server uses real-time inbound carrier webhooks (https://usaverifypro.com/api/worldwide/webhook). As soon as carrier towers receive the SMS code, it is written to our database in under 50ms.